home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 4 / Gold Medal Software - Volume 4 (Gold Medal) (1994).iso / os2 / common.arj / COMMON.INF (.txt) < prev   
OS/2 Help File  |  1994-08-06  |  139KB  |  6,492 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Licensing agreement ΓòÉΓòÉΓòÉ
  3.  
  4. The term LICENSE is used to refer to the ASCII file containing a copy of this 
  5. license.  The term PACKAGE here is used to refer to the header files, the 
  6. libraries, the documentation, and LICENSE. The term AUTHOR is used to refer to 
  7. the developer of PACKAGE. 
  8.  
  9. PACKAGE is copyrighted (c) 1993, 1994 by its AUTHOR, Lawrence W. Salomon, Jr. 
  10. and is the sole property of AUTHOR. 
  11.  
  12. You are hereby granted a license to use PACKAGE in your applications and freely 
  13. distribute PACKAGE if and only if the following condition(s) are met: 
  14.  
  15. o All files in PACKAGE are included in the distributed files and remain in 
  16.   their original form. 
  17.  
  18. o If the contents of the PACKAGE are distributed using any of the file 
  19.   compression programs available (PKZIP, ZIP, ZOO, etc.), LICENSE must not be 
  20.   included in the compressed file but instead must remain separate. 
  21.  
  22. o None of the components or any part of any component of PACKAGE may be used or 
  23.   included in a commercial product without the expressed, written consent of 
  24.   AUTHOR.  A commercial product is defined to be a group of one or more 
  25.   applications which are packaged together and sold for profit. 
  26.  
  27. By using any component or any part of any component of PACKAGE, you are 
  28. indicating that you agree to and are thereby bound to the terms of this 
  29. license. 
  30.  
  31.  
  32. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ
  33.  
  34. Do you ever find yourself writing a new program and wishing that you already 
  35. had a routine to parse the command line?  Or how about a routine that performs 
  36. signal processing?  Or maybe a set of linked list functions?  Often times, I 
  37. have often been in this very situation, writing new code then discovering that 
  38. I have need of routines that should be fairly common. 
  39.  
  40. Instead of simply writing the routines for each application that required them, 
  41. I started maintaining my own software library of commonly used routines, which 
  42. you have here.  These routines provide easy access to a host of functions that 
  43. you used to have to write yourself. 
  44.  
  45. The functions are separated into groups, listed below: 
  46.  
  47. o Common routines 
  48. o Buffer routines 
  49. o Communication routines 
  50. o Debugging routines 
  51. o File routines 
  52. o Link-list routines 
  53. o Memory allocation routines 
  54. o Object handling routines 
  55. o Set routines 
  56. o Signal routines 
  57. o Sprite routines 
  58. o String routines 
  59. o Screen I/O routines 
  60. o Windowing routines 
  61.  
  62. Additionally, the following topics are also available: 
  63.  
  64. o Licensing agreement 
  65. o Using Common/2 in your applications 
  66. o About errors, bugs, and suggestions 
  67. o What's New in this Release 
  68.  
  69. A couple of notes are needed: 
  70.  
  71. o As you use Common/2, you may notice that the library seems to have been built 
  72.   out of "spare parts", because there is lacking a tight level of integration. 
  73.   This is true, and I hope to resolve this in the near future by taking such 
  74.   steps as having each function return an error code (like the kernel APIs), 
  75.   and combining the error codes (instead of having a group for the memory 
  76.   routines, another group for the object routines, etc.).  If you have any 
  77.   suggestions on how the library can be made to fit together better, I would be 
  78.   most interested in hearing them. 
  79.  
  80.  
  81. ΓòÉΓòÉΓòÉ 2.1. Using Common/2 in your applications ΓòÉΓòÉΓòÉ
  82.  
  83. Common/2 was compiled using IBM's C-Set++ compiler; compatibility with other 
  84. 32-bit compilers has not been tested.  It does require you to have the 
  85. Programmer's Toolkit installed on your machine or its functional equivalent, 
  86. however.  You should place the files common.h  and cmndefs.h  in a directory 
  87. specified by the INCLUDE environment variable.  Additionally, you should place 
  88. the .LIB files in a directory specified by the LIB environment variable and the 
  89. .DLL files in a directory specified by the LIBPATH environment variable. 
  90.  
  91. Note that <os2.h> must be included before including <common.h>.  Do not 
  92. explicitly include <cmndefs.h> because it is included by <common.h>.  As with 
  93. <os2.h>, before including <common.h> you should define the appropriate 
  94. constants to indicate which portions of the library you would like to use: 
  95.  
  96. INCL_CMNBUF         Buffer routines (CmnBuf) 
  97.  
  98. INCL_CMNCOM         Communication routines (CmnCom) 
  99.  
  100. INCL_CMNDBG         Debugging routines (CmnDbg) 
  101.  
  102. INCL_CMNFIL         File routines (CmnFil) 
  103.  
  104. INCL_CMNLST         Linked list routines (CmnLst) 
  105.  
  106. INCL_CMNMEM         Memory routines (CmnMem) 
  107.  
  108. INCL_CMNOBJ         Object routines (CmnObj) 
  109.  
  110. INCL_CMNSET         Set routines (CmnSet) 
  111.  
  112. INCL_CMNSIG         Signal routines (CmnSig) 
  113.  
  114. INCL_CMNSPR         Sprite routines (CmnSpr) 
  115.  
  116. INCL_CMNSTR         String routines (CmnStr) 
  117.  
  118. INCL_CMNVIO         VIO routines (CmnVio) 
  119.  
  120. INCL_CMNWIN         Window routines (CmnWin) 
  121.  
  122. INCL_COMMONALL      All sections 
  123.  
  124. The general purpose routines (those that begin with Cmn only) are always 
  125. included regardless of the constants defined. 
  126.  
  127.  
  128. ΓòÉΓòÉΓòÉ 2.2. About errors, bugs, and suggestions ΓòÉΓòÉΓòÉ
  129.  
  130. Often, when something doesn't quite work correctly, it is because the wrong 
  131. handle was passed to the function which returned the unexpected result. Before 
  132. crying "wolf", you should first call CmnQueryHandle to insure that you are 
  133. giving the function what it expects. 
  134.  
  135. If that still doesn't help, if you have some suggestions, if you have a set of 
  136. routines that you would like to donate to the library, or if you would like to 
  137. translate the programming reference and header files into other languages, feel 
  138. free to send me mail via the Internet.  My address is "os2man@panix.com".  If 
  139. you are describing what you think is a bug, please describe the steps needed to 
  140. recreate the problem and include code when possible. 
  141.  
  142.  
  143. ΓòÉΓòÉΓòÉ 2.3. What's New in this Release ΓòÉΓòÉΓòÉ
  144.  
  145. Changes resulting in release 1.5.0 include: 
  146.  
  147. o The CmnBuf routines were added. 
  148.  
  149. o The functions CmnFilCopyDiskette() and CmnFilFormatDiskette() were added. 
  150.  
  151. Changes resulting in release 1.4.0 include: 
  152.  
  153. o The library was moved from a .LIB to a .DLL in hopes of someday writing Rexx 
  154.   interfaces for some or all of the routines.  This impacted a number of 
  155.   things: 
  156.  
  157.    - The CmnVio routines, since CmnVioLoadMessage() assumes that messages will 
  158.      be bound (with MSGBIND) to the DLL and not the EXE file; if an EXE uses 
  159.      MSGBIND to bind its messages to itself, CmnVioLoadMessage() (and thus 
  160.      CmnVioDisplayMessage(), since it is dependent on the former) would return 
  161.      an error. 
  162.  
  163.    - If you write an application that uses non of the PM-dependent routines 
  164.      (CmnSpr and CmnWin), and tried to run the application in a non-PM 
  165.      environment (e.g. booting from the installation diskettes), OS/2 would 
  166.      return an error since, by virtue of the fact that your application is 
  167.      linked to the DLL, PM is required.  To alleviate this problem, the DLLs 
  168.      have multiplied from two to four, and a naming convention was established 
  169.      to allow for this. 
  170.  
  171.      The format of the DLL and LIB file names is CMN32te. "t" is the "threaded" 
  172.      option and can be S for single-threaded or M for multi-threaded.  "e" is 
  173.      the "environment" option and can be V for routines that do not require PM 
  174.      (VIO), or P for routines that do require PM. 
  175.  
  176. o 16-bit support was removed.  This was due to the fact that we're in the 
  177.   second release of a 32-bit OS/2, so 16-bit seemed rather redundant.  The code 
  178.   for all existing functions is still there, but no new development will make 
  179.   provisions for 16-bit compatibility, nor will the 16-bit version of the 
  180.   library be released in this package.  Should you need this, contact me via 
  181.   email. 
  182.  
  183. o The constant INCL_CMNLIB was renamed to INCL_COMMONALL, in the (admittedly 
  184.   unlikely) event that a CmnLib subsystem is added. 
  185.  
  186. o The constant SPL_ERROR was renamed to SPL_ERR_ERROR to avoid conflicts with 
  187.   the constant of the same name in <pmspl.h>. 
  188.  
  189. o Minor bugs with the CmnCom subsystem were fixed. 
  190.  
  191. o A minor bug with the CmnFilSearchFiles() function was fixed. 
  192.  
  193. o A minor bug with the CmnMemFreeMem() was fixed. 
  194.  
  195. o The CmnFilSplitFilename() function was added. 
  196.  
  197. o The CmnWinSavePosToBuffer() and CmnWinRestorePosFromBuffer() functions were 
  198.   added and the CmnWinSavePosition() and CmnWinRestorePosition() functions were 
  199.   modified to utilize these new functions. 
  200.  
  201. o The functions CmnStrPadString() and CmnStrStripSpace() were added. 
  202.  
  203. o The function CmnVioGetString() has been added. 
  204.  
  205. o The sprite subsystem (INCL_CMNSPR) was added. 
  206.  
  207. o All function pointer typedefs were modified to include the EXPENTRY attribute 
  208.   to allow for non-IBM compilers. 
  209.  
  210.  
  211. ΓòÉΓòÉΓòÉ 3. Common routines ΓòÉΓòÉΓòÉ
  212.  
  213. The purpose of this group is to provide functions which apply to all of the 
  214. function groups.  Listed below are the functions which comprise this group: 
  215.  
  216. o CmnQueryHandle 
  217. o CmnQueryHandleInfo 
  218. o CmnQueryVersion 
  219. o CmnSetHandleInfo 
  220.  
  221.  
  222. ΓòÉΓòÉΓòÉ 3.1. CmnQueryHandle ΓòÉΓòÉΓòÉ
  223.  
  224. CmnQueryHandle 
  225.  
  226. Purpose 
  227.  
  228. This function returns the type of the specified handle. 
  229.  
  230. Syntax 
  231.  
  232. (USHORT)CmnQueryHandle(lhHandle);
  233.  
  234. Parameters 
  235.  
  236. lhHandle (LHANDLE) - specifies the handle to query. 
  237.  
  238. Returns 
  239.  
  240. This function returns one of the following values: 
  241.  
  242. QH_ERROR 
  243. QH_HCCCONNECT 
  244. QH_HCFSEARCH 
  245. QH_HCLLIST 
  246. QH_HCMMEM 
  247. QH_HCOOBJECT 
  248. QH_HCSSET 
  249. QH_HCSSIGNAL 
  250. QH_HCSPLAYGROUND 
  251. QH_HCSSPRITE 
  252.  
  253. Notes 
  254.  
  255. This function does not validate the accessability of the memory corresponding 
  256. to lhHandle.  Thus, a value that specifies an invalid memory location will 
  257. cause the application to trap. 
  258.  
  259. Related information 
  260.  
  261. o CmnQueryHandleInfo 
  262.  
  263.  
  264. ΓòÉΓòÉΓòÉ 3.2. CmnQueryHandleInfo ΓòÉΓòÉΓòÉ
  265.  
  266. CmnQueryHandleInfo 
  267.  
  268. Purpose 
  269.  
  270. This function returns information about the specified handle. 
  271.  
  272. Syntax 
  273.  
  274. (BOOL)CmnQueryHandleInfo(lhHandle,pvInfo);
  275.  
  276. Parameters 
  277.  
  278. lhHandle (LHANDLE) - specifies the handle to query. 
  279.  
  280. pvInfo (PVOID) - points to a handle-specific structure to be initialized.  On 
  281. return, this points to the initialized structure. 
  282.  
  283. Returns 
  284.  
  285. This function returns TRUE if the function is successful, or FALSE otherwise. 
  286.  
  287. Notes 
  288.  
  289. What pvInfo points to depends on the type of the handle specified: 
  290.  
  291. Handle type Buffer type 
  292.  
  293. HCCCONNECT pvInfo should point to a CCCONNECTINFO structure 
  294.  
  295. HCLLIST   pvInfo should point to a CLLISTINFO structure 
  296.  
  297. HCMMEM    pvInfo should point to a CMMEMINFO structure 
  298.  
  299. HCOOBJECT pvInfo should point to a COOBJECTINFO structure 
  300.  
  301. HCSSET    pvInfo should point to a CSSETINFO structure 
  302.  
  303. Related information 
  304.  
  305. o CCCONNECTINFO data type 
  306. o CLLISTINFO data type 
  307. o CMMEMINFO data type 
  308. o COOBJECTINFO data type 
  309. o CSSETINFO data type 
  310. o CmnQueryHandle 
  311. o CmnSetHandleInfo 
  312.  
  313.  
  314. ΓòÉΓòÉΓòÉ 3.3. CmnQueryVersion ΓòÉΓòÉΓòÉ
  315.  
  316. CmnQueryVersion 
  317.  
  318. Purpose 
  319.  
  320. This function returns the major, minor, and revision numbers of the library. 
  321.  
  322. Syntax 
  323.  
  324. (VOID)CmnQueryVersion(pusMajor,pusMinor,pusRev);
  325.  
  326. Parameters 
  327.  
  328. pusMajor (PUSHORT) - points to the variable to receive the major version number 
  329.  
  330. pusMinor (PUSHORT) - points to the variable to receive the minor version number 
  331.  
  332. pusRev (PUSHORT) - points to the variable to receive the revision version 
  333. number 
  334.  
  335.  
  336. ΓòÉΓòÉΓòÉ 3.4. CmnSetHandleInfo ΓòÉΓòÉΓòÉ
  337.  
  338. CmnSetHandleInfo 
  339.  
  340. Purpose 
  341.  
  342. This function sets certain attributes about the specified handle. 
  343.  
  344. Syntax 
  345.  
  346. (BOOL)CmnSetHandleInfo(lhHandle,pvInfo);
  347.  
  348. Parameters 
  349.  
  350. lhHandle (LHANDLE) - specifies the handle to query. 
  351.  
  352. pvInfo (PVOID) - points to a handle-specific structure containing the 
  353. information to set. 
  354.  
  355. Returns 
  356.  
  357. This function returns TRUE if the function is successful, or FALSE otherwise. 
  358.  
  359. Notes 
  360.  
  361. What pvInfo points to depends on the type of the handle specified: 
  362.  
  363. Handle type Buffer type 
  364.  
  365. HCCCONNECT pvInfo should point to a CCCONNECTINFO structure 
  366.  
  367. Related information 
  368.  
  369. o CCCONNECTINFO data type 
  370. o CmnQueryHandle 
  371. o CmnQueryHandleInfo 
  372.  
  373.  
  374. ΓòÉΓòÉΓòÉ 4. Buffer routines ΓòÉΓòÉΓòÉ
  375.  
  376. The purpose of this group is to provide functionality that modifies entire 
  377. buffers which can be comprised of any type of data.  This group could 
  378. eventually be expanded to provide a text buffer engine to be used in building 
  379. editor applications. 
  380.  
  381. Listed below are the functions which comprise this group: 
  382.  
  383. o CmnBufCompressBytes 
  384. o CmnBufDecompressBytes 
  385. o CmnBufDecryptBytes 
  386. o CmnBufEncryptBytes 
  387.  
  388.  
  389. ΓòÉΓòÉΓòÉ 4.1. CmnBufCompressBytes ΓòÉΓòÉΓòÉ
  390.  
  391. CmnBufCompressBytes 
  392.  
  393. Purpose 
  394.  
  395. This function attempts to compress the contents of a buffer. 
  396.  
  397. Syntax 
  398.  
  399. (BOOL)CmnBufCompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf);
  400.  
  401. Parameters 
  402.  
  403. pbInBuf (PBYTE) - points to the buffer containing the data to be compressed. 
  404.  
  405. ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  406.  
  407. pbOutBuf (PBYTE) - points to the buffer to hold the compressed data. 
  408.  
  409. pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer 
  410. pointed to by pbOutBuf.  On return, the variable contains the size of the 
  411. compressed data. 
  412.  
  413. Returns 
  414.  
  415. This function returns TRUE if successful, or FALSE otherwise. 
  416.  
  417. Notes 
  418.  
  419. CmnBufCompressBytes uses a run-length-encoding algorithm when compressing the 
  420. data.  While this algorithm is not expensive in CPU time consumed, it is not 
  421. very good at compressing either and it is not guaranteed that the size of the 
  422. compressed data will be less than the size of the original data. 
  423.  
  424. If you specify NULL for pbOutBuf, no data is written, but pulSzOutBuf will 
  425. still be updated; so, you could specify NULL first to determine the size of the 
  426. buffer needed before actually compressing the data. 
  427.  
  428. Related information 
  429.  
  430. o CmnBufDecompressBytes 
  431.  
  432.  
  433. ΓòÉΓòÉΓòÉ 4.2. CmnBufDecompressBytes ΓòÉΓòÉΓòÉ
  434.  
  435. CmnBufDecompressBytes 
  436.  
  437. Purpose 
  438.  
  439. This function decompresses the contents of a buffer which was compressed 
  440. previously using CmnBufCompressBytes. 
  441.  
  442. Syntax 
  443.  
  444. (BOOL) CmnBufDecompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf);
  445.  
  446. Parameters 
  447.  
  448. pbInBuf (PBYTE) - points to the buffer containing the data to be decompressed. 
  449.  
  450. ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  451.  
  452. pbOutBuf (PBYTE) - points to the buffer to hold the decompressed data. 
  453.  
  454. pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer 
  455. pointed to by pbOutBuf.  On return, the variable contains the size of the 
  456. decompressed data. 
  457.  
  458. Returns 
  459.  
  460. This function returns TRUE if successful, or FALSE otherwise. 
  461.  
  462. Notes 
  463.  
  464. There is no error checking to insure that the buffer was compressed with 
  465. CmnBufCompressBytes.  This responsibility is left to the application designer. 
  466.  
  467. Related information 
  468.  
  469. o CmnBufCompressBytes 
  470.  
  471.  
  472. ΓòÉΓòÉΓòÉ 4.3. CmnBufDecryptBytes ΓòÉΓòÉΓòÉ
  473.  
  474. CmnBufDecryptBytes 
  475.  
  476. Purpose 
  477.  
  478. This function decrypts the contents of a buffer which was encrypted previously 
  479. using CmnBufEncryptBytes. 
  480.  
  481. Syntax 
  482.  
  483. (BOOL)CmnBufDecryptBytes(pbInBuf,ulSzBuf,pbOutBuf);
  484.  
  485. Parameters 
  486.  
  487. pbInBuf (PBYTE) - points to the buffer containing the data to be decrypted. 
  488.  
  489. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  490.  
  491. pbOutBuf (PBYTE) - points to the buffer to contain the decrypted data. 
  492.  
  493. Returns 
  494.  
  495. This function returns TRUE if successful, or FALSE otherwise. 
  496.  
  497. Notes 
  498.  
  499. There is no error checking to insure that the buffer was encrypted with 
  500. CmnBufEncryptBytes.  This responsibility is left to the application designer. 
  501.  
  502. Related information 
  503.  
  504. o CmnBufEncryptBytes 
  505.  
  506.  
  507. ΓòÉΓòÉΓòÉ 4.4. CmnBufEncryptBytes ΓòÉΓòÉΓòÉ
  508.  
  509. CmnBufEncryptBytes 
  510.  
  511. Purpose 
  512.  
  513. This function encrypts a buffer using the NSS algorithm. 
  514.  
  515. Syntax 
  516.  
  517. (BOOL)CmnBufEncryptBytes(pbInBuf,ulSzBuf,pbOutBuf);
  518.  
  519. Parameters 
  520.  
  521. pbInBuf (PBYTE) - points to the buffer containing the data to be encrypted. 
  522.  
  523. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  524.  
  525. pbOutBuf (PBYTE) - points to the buffer to contain the encrypted data. 
  526.  
  527. Returns 
  528.  
  529. This function returns TRUE if successful, or FALSE otherwise. 
  530.  
  531. Notes 
  532.  
  533. NSS is an acronym for not-so-secure and describes the strength of the algorithm 
  534. used.  The encrypted data is always of the same length as the original data. 
  535. It is suggested that this function be used in conjunction with the function 
  536. CmnBufCompressBytes to result in data that will not so easily be decyphered. 
  537.  
  538. Related information 
  539.  
  540. o CmnBufDecryptBytes 
  541.  
  542.  
  543. ΓòÉΓòÉΓòÉ 5. Communication routines ΓòÉΓòÉΓòÉ
  544.  
  545. The purpose of this group is to provide easy to use communication routines for 
  546. client/server application development.  The bidirectional connections are 
  547. implemented via named pipes and can thus work locally or over a LAN. 
  548.  
  549. A client simply opens a connection and starts reading and/or writing to it, 
  550. while a server waits for a connection and reads/writes to a private connection 
  551. which is derived from the "control connection" (see the pseudocode below). This 
  552. yields three connection types: 
  553.  
  554.  1. Client 
  555.  2. Server 
  556.  3. Server-connect 
  557.  
  558. /* Client */
  559. HCCCONNECT hccConnect;
  560.  
  561. CmnComOpenConnection(...,&hccConnect);
  562. CmnComReadData(hccConnect,...);
  563. CmnComWriteData(hccConnect,...);
  564. CmnComSendControl(hccConnect,CSC_CTRL_CLOSE);
  565. CmnComCloseConnection(&hccConnect);
  566. /* ------------------------------------------------ */
  567. /* Server */
  568. HCCCONNECT hccServer;
  569. HCCCONNECT hccConnect;
  570.  
  571. CmnComOpenConnection(...,&hccServer);
  572.  
  573. CmnComWaitConnection(hccServer,&hccConnect);
  574. /****************************************************/
  575. /* For peer-to-peer, we would close hccServer after */
  576. /* establishing a data connection with a client     */
  577. /****************************************************/
  578. CmnComReadData(hccConnect,...);
  579. CmnComWriteData(hccConnect,...);
  580. CmnComSendControl(hccConnect,CSC_CLOSE);
  581. CmnComCloseConnection(&hccServer);
  582.  
  583. CmnComCloseConnection(&hccConnect);
  584.  
  585. Using this implementation strategy has two advantages:  1) it is very easy to 
  586. create client/server or peer-to-peer applications and 2) programmers familiar 
  587. with TCP/IP will find this very familiar. 
  588.  
  589. Data is written in the form of packets, allowing for a handshaking protocol to 
  590. be used by the functions.  This insures that the other end receives the data 
  591. written into the connection. 
  592.  
  593. Listed below are the functions which comprise this group: 
  594.  
  595. o CmnComCloseConnection 
  596. o CmnComOpenConnection 
  597. o CmnComQueryData 
  598. o CmnComReadData 
  599. o CmnComSendControl 
  600. o CmnComWaitConnection 
  601. o CmnComWriteData 
  602.  
  603.  
  604. ΓòÉΓòÉΓòÉ 5.1. CmnComCloseConnection ΓòÉΓòÉΓòÉ
  605.  
  606. CmnComCloseConnection 
  607.  
  608. Purpose 
  609.  
  610. Closes a connection. 
  611.  
  612. Syntax 
  613.  
  614. (COMERROR)CmnComCloseConnection(phccConnect)
  615.  
  616. Parameters 
  617.  
  618. phccConnect (PHCCCONNECT) - points to the variable specifying the handle of the 
  619. connection.  On return, this variable contains NULL. 
  620.  
  621. Returns 
  622.  
  623. This function returns one of the following values: 
  624.  
  625. COM_ERR_NOERROR 
  626. COM_ERR_BADHANDLE 
  627.  
  628. Notes 
  629.  
  630. Use CmnComCloseConnection to close a specific connection.  Note that closing a 
  631. server connection does not close any private data connections that were 
  632. established from the server connection. 
  633.  
  634. It is recommended to send a CSC_CLOSE control code to indicate to the 
  635. application on the other side that the connection is about to be closed. 
  636.  
  637. Related information 
  638.  
  639. o HCCCONNECT data type 
  640. o CmnComOpenConnection 
  641. o CmnComSendControl 
  642.  
  643.  
  644. ΓòÉΓòÉΓòÉ 5.2. CmnComOpenConnection ΓòÉΓòÉΓòÉ
  645.  
  646. CmnComOpenConnection 
  647.  
  648. Purpose 
  649.  
  650. Creates a new connection handle based upon the information provided. 
  651.  
  652. Syntax 
  653.  
  654. (COMERROR)CmnComOpenConnection(pcoiInfo,phccConnect)
  655.  
  656. Parameters 
  657.  
  658. pcoiInfo (PCCOPENINFO) - points to a CCOPENINFO structure which describes the 
  659. connection to be created.  This parameter is required.  On return, the usAttr 
  660. field specifies the type of connection that was established (e.g. client, 
  661. server, or server-connect). 
  662.  
  663. phccConnect (PHCCCONNECT) - points to the variable which receives the new 
  664. connection handle. 
  665.  
  666. Returns 
  667.  
  668. This function returns one of the following values: 
  669.  
  670. COM_ERR_NOERROR 
  671. COM_ERR_BADARGUMENT 
  672. COM_ERR_CC_CLOSE 
  673. COM_ERR_CC_RESET 
  674. COM_ERR_ERROR 
  675. COM_ERR_INITFAILED 
  676. COM_ERR_NOCONNECTION 
  677. COM_ERR_NOMEMORY 
  678. COM_ERR_READFAILED 
  679. COM_ERR_TIMEOUT 
  680.  
  681. Notes 
  682.  
  683. Use CmnComOpenConnection to create a new connection.  If the achMachine field 
  684. of the CCOPENINFO structure is empty, then the connection is a local one.  Note 
  685. that the timeout value (the lTimeout field) is changeable via CmnSetHandleInfo. 
  686. This allows you to set a timeout now until a connection is established and then 
  687. change it later for data retrieval. 
  688.  
  689. Server connections cannot be read from or written to.  Instead, they are used 
  690. to call CmnComWaitConnection to establish a server-connect connection for data 
  691. transfer. 
  692.  
  693. Related information 
  694.  
  695. o CCOPENINFO data type 
  696. o HCCCONNECT data type 
  697. o CmnComCloseConnection 
  698. o CmnComWaitConnection 
  699.  
  700.  
  701. ΓòÉΓòÉΓòÉ 5.3. CmnComQueryData ΓòÉΓòÉΓòÉ
  702.  
  703. CmnComQueryData 
  704.  
  705. Purpose 
  706.  
  707. Checks to see if data is available for reading. 
  708.  
  709. Syntax 
  710.  
  711. (COMERROR)CmnComQueryData(hccConnect,pulData)
  712.  
  713. Parameters 
  714.  
  715. hccConnect (HCCCONNECT) - specifies the connection handle. 
  716.  
  717. pulData (PULONG) - points to the variable which receives the number of bytes 
  718. available. 
  719.  
  720. Returns 
  721.  
  722. This function returns one of the following values: 
  723.  
  724. COM_ERR_NOERROR 
  725. COM_ERR_BADHANDLE 
  726.  
  727. Notes 
  728.  
  729. Use CmnComQueryData to determine if data is available on the connection for 
  730. reading.  Note that if the application writes data to the connection and the 
  731. receiving end does not read the data before this function is called, pusData 
  732. will return 0 bytes available. 
  733.  
  734. Related information 
  735.  
  736. o HCCCONNECT data type 
  737. o CmnComReadData 
  738. o CmnComWriteData 
  739.  
  740.  
  741. ΓòÉΓòÉΓòÉ 5.4. CmnComReadData ΓòÉΓòÉΓòÉ
  742.  
  743. CmnComReadData 
  744.  
  745. Purpose 
  746.  
  747. Reads data from a connection and sends an acknowledgement to the other end of 
  748. the connection. 
  749.  
  750. Syntax 
  751.  
  752. (COMERROR)CmnComReadData(hccConnect,pvBuf,pulSzBuf)
  753.  
  754. Parameters 
  755.  
  756. hccConnect (HCCCONNECT) - specifies the connection handle. 
  757.  
  758. pvBuf (PVOID) - points to the buffer to receive the data. 
  759.  
  760. pulSzBuf (PULONG) - points to the variable specifying the size of the buffer 
  761. pointed to by pvBuf.  On return, this variable contains the number of bytes 
  762. actually read from the connection. 
  763.  
  764. Returns 
  765.  
  766. This function returns one of the following values: 
  767.  
  768. COM_ERR_NOERROR 
  769. COM_ERR_BADDATA 
  770. COM_ERR_BADHANDLE 
  771. COM_ERR_BUFFERTOOLARGE 
  772. COM_ERR_CC_CLOSE 
  773. COM_ERR_CC_RESET 
  774. COM_ERR_ERROR 
  775. COM_ERR_INITFAILED 
  776. COM_ERR_READFAILED 
  777. COM_ERR_TIMEOUT 
  778.  
  779. Notes 
  780.  
  781. Use CmnComReadData to read data from a connection.  Note that if the buffer 
  782. specified is not large enough to contain the data in the current packet, the 
  783. additional bytes are discarded.  Thus, if a predetermined, fixed data length is 
  784. not used, it is highly recommended that CmnComQueryData is called to retrieve 
  785. the size of the current packet.  If there is no data at the front of the 
  786. connection for the application to read, this function waits until there is data 
  787. or until a timeout occurs. 
  788.  
  789. For 16-bit applications, there is a limit of 61440 bytes that can be read in 
  790. one call. 
  791.  
  792. Note that if the other end sends a control code, no data is placed into pvBuf 
  793. but the appropriate COM_ERR_CC_* code is returned instead. 
  794.  
  795. Related information 
  796.  
  797. o HCCCONNECT data type 
  798. o CmnComQueryData 
  799. o CmnComSendControl 
  800. o CmnComWriteData 
  801.  
  802.  
  803. ΓòÉΓòÉΓòÉ 5.5. CmnComSendControl ΓòÉΓòÉΓòÉ
  804.  
  805. CmnComSendControl 
  806.  
  807. Purpose 
  808.  
  809. This function sends a control code to the other end of the connection. 
  810.  
  811. Syntax 
  812.  
  813. (COMERROR)CmnComSendControl(hccConnect,ulCtrlCode)
  814.  
  815. Parameters 
  816.  
  817. hccConnect (HCCCONNECT) - specifies the connection handle. 
  818.  
  819. ulCtrlCode (ULONG) - specifies a CSC_* control code. 
  820.  
  821. Returns 
  822.  
  823. This function returns one of the following values: 
  824.  
  825. COM_ERR_NOERROR 
  826. COM_ERR_BADACK 
  827. COM_ERR_BADCONTROL 
  828. COM_ERR_BADHANDLE 
  829. COM_ERR_NOTIMPLEMENTED 
  830. COM_ERR_WRITEFAILED 
  831.  
  832. Notes 
  833.  
  834. Use CmnComSendControl to send a control code to the other end of the 
  835. connection.  "Control codes" are predefined data packets which indicate that a 
  836. particular action is to be performed.  For CSC_CLOSE control codes, it is 
  837. conceivable that the other end of the connection is able to close the 
  838. connection before the packet acknowledgement is read by this end.  Thus, a 
  839. return value of COM_ERR_BADACK should be accounted for in your application 
  840. code. It is highly recommended that a CSC_CLOSE control code is sent before 
  841. closing the connection to allow the other end to perform any necessary cleanup 
  842. (such as reading any data that is expected). 
  843.  
  844. Note that this function unconditionally waits for an acknowledgement. 
  845.  
  846. Related information 
  847.  
  848. o CSC_ constants 
  849. o HCCCONNECT data type 
  850.  
  851.  
  852. ΓòÉΓòÉΓòÉ 5.6. CmnComWaitConnection ΓòÉΓòÉΓòÉ
  853.  
  854. CmnComWaitConnection 
  855.  
  856. Purpose 
  857.  
  858. Waits for a connection from a client. 
  859.  
  860. Syntax 
  861.  
  862. (COMERROR)CmnComWaitConnection(hccServer,phccConnect)
  863.  
  864. Parameters 
  865.  
  866. hccServer (HCCCONNECT) - specifies the server connection handle. 
  867.  
  868. phccConnect (PHCCCONNECT) - points to the variable which receives the created 
  869. server-connect connection handle. 
  870.  
  871. Returns 
  872.  
  873. This function returns one of the following values: 
  874.  
  875. COM_ERR_NOERROR 
  876. COM_ERR_BADHANDLE 
  877. COM_ERR_ERROR 
  878. COM_ERR_INITFAILED 
  879. COM_ERR_NOMEMORY 
  880. COM_ERR_NONEFREE 
  881. COM_ERR_NOTSERVER 
  882. COM_ERR_TIMEOUT 
  883. COM_ERR_WRITEFAILED 
  884.  
  885. Notes 
  886.  
  887. Use CmnComWaitConnection to listen for a connection by a client. When this 
  888. happens, a server-connect connection is created for data exchange between the 
  889. applications.  This allows the hccServer handle to continue to listen for other 
  890. connections via subsequent calls to this function.  If peer-to-peer 
  891. communications are desired, CmnComCloseConnection can be called to close the 
  892. server connection so that no further data connections are established. 
  893.  
  894. A server may have up to 256 associated server-connect connections spawned from 
  895. it, but this may exceed a system-imposed limit. 
  896.  
  897. Related information 
  898.  
  899. o HCCCONNECT data type 
  900. o CmnComCloseConnection 
  901.  
  902.  
  903. ΓòÉΓòÉΓòÉ 5.7. CmnComWriteData ΓòÉΓòÉΓòÉ
  904.  
  905. CmnComWriteData 
  906.  
  907. Purpose 
  908.  
  909. Writes data to a connection and waits for an acknowledgement from the other end 
  910. of the connection. 
  911.  
  912. Syntax 
  913.  
  914. (COMERROR)CmnComWriteData(hccConnect,pvBuf,ulSzBuf)
  915.  
  916. Parameters 
  917.  
  918. hccConnect (HCCCONNECT) - specifies the connection handle. 
  919.  
  920. pvBuf (PVOID) - points to the buffer containing the data to write. 
  921.  
  922. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuf. 
  923.  
  924. Returns 
  925.  
  926. This function returns one of the following values: 
  927.  
  928. COM_ERR_NOERROR 
  929. COM_ERR_BADACK 
  930. COM_ERR_BADHANDLE 
  931. COM_ERR_BUFFERTOOLARGE 
  932. COM_ERR_WRITEFAILED 
  933.  
  934. Notes 
  935.  
  936. Use CmnComWriteData to write data to a connection. Acknowledgement receipt is 
  937. handled transparently by the function. 
  938.  
  939. For 16-bit applications, there is a limit of 61440 bytes that can be written in 
  940. one call. 
  941.  
  942. Related information 
  943.  
  944. o HCCCONNECT data type 
  945. o CmnComReadData 
  946.  
  947.  
  948. ΓòÉΓòÉΓòÉ 6. Debugging routines ΓòÉΓòÉΓòÉ
  949.  
  950. The purpose of this group is to provide aid in debugging your applications. 
  951. While they are not anything spectacular, I have found them helpful from time to 
  952. time. 
  953.  
  954. Listed below are the functions which comprise this group: 
  955.  
  956. o CmnDbgWriteBinary 
  957. o CmnDbgWriteRecord 
  958. o CmnDbgWriteText 
  959.  
  960.  
  961. ΓòÉΓòÉΓòÉ 6.1. CmnDbgWriteBinary ΓòÉΓòÉΓòÉ
  962.  
  963. CmnDbgWriteBinary 
  964.  
  965. Purpose 
  966.  
  967. This function writes the contents of a buffer to a file. 
  968.  
  969. Syntax 
  970.  
  971. (SHORT)CmnDbgWriteBinary(pvFile,
  972.                          usFileType,
  973.                          pvBuf,
  974.                          usSzBuf);
  975.  
  976. Parameters 
  977.  
  978. pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
  979. in <stdio.h>). 
  980.  
  981. usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
  982. pvFile. 
  983.  
  984. pvBuf (PVOID) - points to the buffer to be written. 
  985.  
  986. usSzBuf (USHORT) - specifies the size of the buffer pointed to by pvBuf. 
  987.  
  988. Returns 
  989.  
  990. This function returns the number of bytes successfully written, or DWT_ERROR 
  991. otherwise. 
  992.  
  993. Notes 
  994.  
  995. Use CmnDbgWriteBinary to write the contents of a buffer to a specific file. 
  996. The format of the output is a combination of hexadecimal on the left side with 
  997. ASCII representation on the right with a vertical line separating the two. 
  998. Unprintable characters (as defined by the function isprint) are displayed as 
  999. periods in the ASCII output. 
  1000.  
  1001. Related information 
  1002.  
  1003. o DWT_TYPE_ constants 
  1004. o CmnDbgWriteText 
  1005.  
  1006.  
  1007. ΓòÉΓòÉΓòÉ 6.2. CmnDbgWriteRecord ΓòÉΓòÉΓòÉ
  1008.  
  1009. CmnDbgWriteRecord 
  1010.  
  1011. Purpose 
  1012.  
  1013. This function writes the contents of a structure to a file. 
  1014.  
  1015. Syntax 
  1016.  
  1017. (SHORT)CmnDbgWriteRecord(pvFile,
  1018.                          usFileType,
  1019.                          pcFormat,
  1020.                          usNumRecs,
  1021.                          pbBuf);
  1022.  
  1023. Parameters 
  1024.  
  1025. pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
  1026. in <stdio.h>). 
  1027.  
  1028. usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
  1029. pvFile. 
  1030.  
  1031. pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing 
  1032. the format of the structure to be written. 
  1033.  
  1034. usNumRecs (USHORT) - specifies the number of records pointed to by pcFormat. 
  1035.  
  1036. pbBuf (PBYTE) - points to the structure to write. 
  1037.  
  1038. Returns 
  1039.  
  1040. This function returns the number of fields in the structure successfully 
  1041. written, or DWT_ERROR otherwise. 
  1042.  
  1043. Notes 
  1044.  
  1045. Use CmnDbgWriteRecord to write the contents of a record to a specific file. 
  1046. This function calls CmnDbgWriteText to actually write the results, so the file 
  1047. is guaranteed to be flushed after every field is output. 
  1048.  
  1049. Related information 
  1050.  
  1051. o DWT_TYPE_ constants 
  1052. o CSLINEDESC data type 
  1053. o CmnDbgWriteText 
  1054.  
  1055.  
  1056. ΓòÉΓòÉΓòÉ 6.3. CmnDbgWriteText ΓòÉΓòÉΓòÉ
  1057.  
  1058. CmnDbgWriteText 
  1059.  
  1060. Purpose 
  1061.  
  1062. This function writes text to a specified file. 
  1063.  
  1064. Syntax 
  1065.  
  1066. (SHORT)CmnDbgWriteText(pvFile,usFileType,pchFmt,...);
  1067.  
  1068. Parameters 
  1069.  
  1070. pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
  1071. in <stdio.h>). 
  1072.  
  1073. usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
  1074. pvFile. 
  1075.  
  1076. pchFmt (PCHAR) - points to the format string (as in the C printf routine). 
  1077.  
  1078. ... (va_list) - specifies any additional arguments referred to by pchFmt 
  1079.  
  1080. Returns 
  1081.  
  1082. This function returns the number of characters successfully written, or 
  1083. DWT_ERROR otherwise. 
  1084.  
  1085. Notes 
  1086.  
  1087. Use CmnDbgWriteText to write information to a file.  By specifying 
  1088. DWT_TYPE_FILE for usFileType, you can use a predefined stream (stdout, stderr) 
  1089. or any other file that is already opened. Specifying DWT_TYPE_NAME indicates 
  1090. that this function should open the file in append mode and close it before 
  1091. returning. 
  1092.  
  1093. o DWT_TYPE_ constants 
  1094.  
  1095.  
  1096. ΓòÉΓòÉΓòÉ 7. File routines ΓòÉΓòÉΓòÉ
  1097.  
  1098. The purpose of this group is to provide functions which help you perform common 
  1099. tasks without a lot of the work. 
  1100.  
  1101. Listed below are the functions which comprise this group: 
  1102.  
  1103. o CmnFilCopyDiskette 
  1104. o CmnFilCreateSearch 
  1105. o CmnFilDestroySearch 
  1106. o CmnFilFormatDiskette 
  1107. o CmnFilQueryExtAttribute 
  1108. o CmnFilQueryLabel 
  1109. o CmnFilSearchFiles 
  1110. o CmnFilSetExtAttribute 
  1111. o CmnFilSplitFilename 
  1112.  
  1113.  
  1114. ΓòÉΓòÉΓòÉ 7.1. CmnFilCopyDiskette ΓòÉΓòÉΓòÉ
  1115.  
  1116. CmnFilCopyDiskette 
  1117.  
  1118. Purpose 
  1119.  
  1120. This function copies the contents of a diskette onto another diskette. 
  1121.  
  1122. Syntax 
  1123.  
  1124. (BOOL)CmnFilCopyDiskette(chSrc,chDest,ulOptions,pfnCallback,pvUser);
  1125.  
  1126. Parameters 
  1127.  
  1128. chSrc (CHAR) - specifies the source drive and can be upper- or lower-case. 
  1129.  
  1130. chDest (CHAR) - specifies the destination drive and can be upper- or 
  1131. lower-case. 
  1132.  
  1133. ulOptions (ULONG) - one or more FCD_OPT_* constants controlling the behavior of 
  1134. this function. 
  1135.  
  1136. pfnCallback (PFNDISKIO) - points to a callback function.  See below for more 
  1137. information. 
  1138.  
  1139. pvUser (PVOID) - pointer to user data which is passed to pfnCallback. 
  1140.  
  1141. Returns 
  1142.  
  1143. This function returns TRUE if successful, or FALSE otherwise. 
  1144.  
  1145. Notes 
  1146.  
  1147. Use CmnFilCopyDiskette to copy one diskette onto another.  The power of this 
  1148. function is in the use of pfnCallback; this callback function is called by 
  1149. CmnFilCopyDiskette in various times for various reasons.  See the items listed 
  1150. below for more information on the specifics of each constant. 
  1151.  
  1152. Related information 
  1153.  
  1154. o FCD_TYPE_ constants 
  1155. o FCD_MSG_ constants 
  1156. o FCD_ERR_ constants 
  1157. o PFNDISKIO function 
  1158.  
  1159.  
  1160. ΓòÉΓòÉΓòÉ 7.2. CmnFilCreateSearch ΓòÉΓòÉΓòÉ
  1161.  
  1162. CmnFilCreateSearch 
  1163.  
  1164. Purpose 
  1165.  
  1166. This function creates a search handle for use in subsequent calls to 
  1167. CmnFilSearchFiles. 
  1168.  
  1169. Syntax 
  1170.  
  1171. (BOOL)CmnFilCreateSearch(pchMask,ulAttr,phcSearch);
  1172.  
  1173. Parameters 
  1174.  
  1175. pchMask (PCHAR) - points to the file mask to be used when searching for the 
  1176. files. 
  1177.  
  1178. ulAttr (ULONG) - specifies a combination of FCS_ATTR_ constants which specify 
  1179. the types of files to search for. 
  1180.  
  1181. phcSearch (PHCFSEARCH) - on return, this points to the variable containing the 
  1182. created search handle. 
  1183.  
  1184. Returns 
  1185.  
  1186. This function returns TRUE if successful, or FALSE otherwise. 
  1187.  
  1188. Notes 
  1189.  
  1190. Use CmnFilCreateSearch to create a search handle for use in calls to 
  1191. CmnFilSearchFiles.  Note that, unlike DosFindFirst, "normal" files (those with 
  1192. no special attributes) are not searched for unless FCS_ATTR_NORMAL is specified 
  1193. in ulAttr. 
  1194.  
  1195. Related information 
  1196.  
  1197. o FCS_ATTR_ constants 
  1198. o HCFSEARCH data type 
  1199. o CmnFilSearchFiles 
  1200.  
  1201.  
  1202. ΓòÉΓòÉΓòÉ 7.3. CmnFilDestroySearch ΓòÉΓòÉΓòÉ
  1203.  
  1204. CmnFilDestroySearch 
  1205.  
  1206. Purpose 
  1207.  
  1208. This function destroys a search handle created by CmnFilCreateSearch. 
  1209.  
  1210. Syntax 
  1211.  
  1212. (BOOL)CmnFilDestroySearch(hcSearch);
  1213.  
  1214. Parameters 
  1215.  
  1216. phcSearch (PHCFSEARCH) - points to the variable specifying the search handle to 
  1217. destroy.  On return, this variable contains NULL. 
  1218.  
  1219. Returns 
  1220.  
  1221. This function returns TRUE if successful, or FALSE otherwise. 
  1222.  
  1223. Notes 
  1224.  
  1225. Use CmnFilDestroySearch to free any resources consumed by the search functions. 
  1226.  
  1227. Related information 
  1228.  
  1229. o HCFSEARCH data type 
  1230. o CmnFilCreateSearch 
  1231.  
  1232.  
  1233. ΓòÉΓòÉΓòÉ 7.4. CmnFilFormatDiskette ΓòÉΓòÉΓòÉ
  1234.  
  1235. CmnFilFormatDiskette 
  1236.  
  1237. Purpose 
  1238.  
  1239. This function formats a diskette. 
  1240.  
  1241. Syntax 
  1242.  
  1243. (BOOL)CmnFilFormatDiskette(chDrive,pfiInfo,pfnCallback,pvUser);
  1244.  
  1245. Parameters 
  1246.  
  1247. chDrive (CHAR) - specifies the drive in which the diskette to be formatted is 
  1248. placed. 
  1249.  
  1250. pfiInfo (PCFFORMATINFO) - points to a CFFORMATINFO structure specifying the 
  1251. format parameters to be used.  If NULL the parameters for the diskette are used 
  1252. (if the diskette is already formatted), or the defaults for the drive are used 
  1253. (if the diskette is not already formatted). 
  1254.  
  1255. pfnCallback (PFNDISKIO) - points to a callback function.  See below for more 
  1256. information. 
  1257.  
  1258. pvUser (PVOID) - pointer to user data which is passed to pfnCallback. 
  1259.  
  1260. Returns 
  1261.  
  1262. This function returns TRUE if successful, or FALSE otherwise. 
  1263.  
  1264. Notes 
  1265.  
  1266. Use CmnFilFormatDiskette to format a diskette.  The power of this function is 
  1267. in the use of pfnCallback; this callback function is called by 
  1268. CmnFilFormatDiskette in various times for various reasons.  See the items 
  1269. listed below for more information on the specifics of each constant. 
  1270.  
  1271. The boot sector that is written to the diskette consists of a program at offset 
  1272. 0x40 (which is jumped to by the first two bytes of the boot sector), which 
  1273. loads and displays an ASCIIZ string beginning at offset 0x80.  The default 
  1274. message placed there is a NULL-string.  To specify your own string to be 
  1275. displayed, you need to read track 0, head 0, sector 0, and copy your string 
  1276. into the buffer containing the sector's data at the correct offset, and then 
  1277. write the new contents to track 0, head 0, sector 0. 
  1278.  
  1279. When determining the string to be written, be aware that - on the rarely found 
  1280. machines with single-head, single-density floppy drives - you only have 30 
  1281. bytes (including the terminating 0) for the string's contents. 
  1282.  
  1283. Related information 
  1284.  
  1285. o FCD_TYPE_ constants 
  1286. o FCD_MSG_ constants 
  1287. o FCD_ERR_ constants 
  1288. o CFFORMATINFO data type 
  1289. o PFNDISKIO function 
  1290.  
  1291.  
  1292. ΓòÉΓòÉΓòÉ 7.5. CmnFilQueryExtAttribute ΓòÉΓòÉΓòÉ
  1293.  
  1294. CmnFilQueryExtAttribute 
  1295.  
  1296. Purpose 
  1297.  
  1298. This function queries the value of an extended attribute written by 
  1299. CmnFilSetExtAttribute. 
  1300.  
  1301. Syntax 
  1302.  
  1303. (BOOL)CmnFilQueryExtAttribute(pchFile,
  1304.                               pchVendor,
  1305.                               pchAppl,
  1306.                               pchName,
  1307.                               pusAttr,
  1308.                               pbValue,
  1309.                               pusSzValue);
  1310.  
  1311. Parameters 
  1312.  
  1313. pchFile (PCHAR) - points to the name of the file containing the extended 
  1314. attributes to query. 
  1315.  
  1316. pchVendor (PCHAR) - points to the name of the vendor whose application wrote 
  1317. the extended attribute or an FEA_ constant. 
  1318.  
  1319. pchAppl (PCHAR) - points to the name of the application which wrote the 
  1320. extended attribute. 
  1321.  
  1322. pchName (PCHAR) - points to the name of the extended attribute. 
  1323.  
  1324. pusAttr (PUSHORT) - points to the attribute of the extended attribute. 
  1325.  
  1326. pbValue (PBYTE) - points to a buffer to receive the results. On return, the 
  1327. buffer contains the value of the extended attribute. 
  1328.  
  1329. pusSzValue (PUSHORT) - points to a variable specifying the size of pbValue.  On 
  1330. return, this points to the number of bytes copied to the buffer. 
  1331.  
  1332. Returns 
  1333.  
  1334. This function returns TRUE if successful, or FALSE otherwise. 
  1335.  
  1336. Notes 
  1337.  
  1338. Use CmnFilQueryExtAttribute to query an extended attribute of a file.  Because 
  1339. this call (and CmnFilSetExtAttribute) enforces the convention stated in the IBM 
  1340. Programming Toolkit's "Programming Guide", this function is only guaranteed to 
  1341. return meaningful results if the extended attribute was originally written by 
  1342. CmnFilSetExtAttribute. 
  1343.  
  1344. If an FEA_ constant is specified for pchVendor, pchAppl and pchName are 
  1345. ignored. 
  1346.  
  1347. Related information 
  1348.  
  1349. o FEA_ constants 
  1350. o CmnFilSetExtAttribute 
  1351.  
  1352.  
  1353. ΓòÉΓòÉΓòÉ 7.6. CmnFilQueryLabel ΓòÉΓòÉΓòÉ
  1354.  
  1355. CmnFilQueryLabel 
  1356.  
  1357. Purpose 
  1358.  
  1359. This function returns the label on the diskette in the specified drive. 
  1360.  
  1361. Syntax 
  1362.  
  1363. (BOOL)CmnFilQueryLabel(chDrive,pchLabel);
  1364.  
  1365. Parameters 
  1366.  
  1367. chDrive (CHAR) - specifies the drive to query. 
  1368.  
  1369. pchLabel (PCHAR) - points to the buffer to hold the label.  On return, this 
  1370. buffer holds the diskette label if successful. 
  1371.  
  1372. Returns 
  1373.  
  1374. This function returns TRUE if successful, or FALSE otherwise. 
  1375.  
  1376. Notes 
  1377.  
  1378. Use CmnFilQueryLabel to determine the label of the diskette in the specified 
  1379. drive.  This function will not cause a "hard error" popup to appear if no 
  1380. diskette is in the drive; instead, this function will return FALSE. 
  1381.  
  1382.  
  1383. ΓòÉΓòÉΓòÉ 7.7. CmnFilSearchFiles ΓòÉΓòÉΓòÉ
  1384.  
  1385. CmnFilSearchFiles 
  1386.  
  1387. Purpose 
  1388.  
  1389. This function returns the next file found that has the characteristics 
  1390. specified when the search handle was created. 
  1391.  
  1392. Syntax 
  1393.  
  1394. (LONG)CmnFilSearchFiles(hcSearch,pchBuf,ulSzBuf);
  1395.  
  1396. Parameters 
  1397.  
  1398. hcSearch (HCFSEARCH) - specifies the search handle. 
  1399.  
  1400. pchBuf (PCHAR) - points to a buffer to receive the results.  On return, the 
  1401. buffer contains the fully qualified name of the next file found. 
  1402.  
  1403. ulSzBuf (ULONG) - specifies the size of pchBuf. 
  1404.  
  1405. Returns 
  1406.  
  1407. This function returns the attribute of the file found as a combination of 
  1408. FCS_ATTR_ constants if successful, FSF_NOFILES if no more files were found that 
  1409. match the criteria, or FSF_ERROR if an error occurred. 
  1410.  
  1411. Notes 
  1412.  
  1413. Use CmnFilSearchFiles to search for the next file that exactly matches the 
  1414. criteria (file mask and attribute) specified in the search handle. Note that 
  1415. the attribute match must be exact (i.e. not a subset).  For example, if file 
  1416. "A" has the archive, hidden, system, and read-only attributes set, it will not 
  1417. be found unless you specify all four of its attributes. 
  1418.  
  1419. Related information 
  1420.  
  1421. o FCS_ATTR_ constants 
  1422. o HCFSEARCH data type 
  1423. o CmnFilCreateSearch 
  1424.  
  1425.  
  1426. ΓòÉΓòÉΓòÉ 7.8. CmnFilSetExtAttribute ΓòÉΓòÉΓòÉ
  1427.  
  1428. CmnFilSetExtAttribute 
  1429.  
  1430. Purpose 
  1431.  
  1432. This function writes an extended attribute to the specified file. 
  1433.  
  1434. Syntax 
  1435.  
  1436. (BOOL)CmnFilSetExtAttribute(pchFile,
  1437.                             usAttr,
  1438.                             pchVendor,
  1439.                             pchAppl,
  1440.                             pchName,
  1441.                             pbValue,
  1442.                             usSzValue);
  1443.  
  1444. Parameters 
  1445.  
  1446. pchFile (PCHAR) - points to the name of the file containing the extended 
  1447. attributes to set. 
  1448.  
  1449. usAttr (USHORT) - points to the attribute of the extended attribute. 
  1450.  
  1451. pchVendor (PCHAR) - points to the name of the vendor whose application is 
  1452. writing the extended attribute or an FEA_ constant. 
  1453.  
  1454. pchAppl (PCHAR) - points to the name of the application which is writing the 
  1455. extended attribute. 
  1456.  
  1457. pchName (PCHAR) - points to the name of the extended attribute. 
  1458.  
  1459. pbValue (PBYTE) - points to a buffer containing the value of the extended 
  1460. attribute. 
  1461.  
  1462. usSzValue (USHORT) - specifies the size of pbValue. 
  1463.  
  1464. Returns 
  1465.  
  1466. This function returns TRUE if successful, or FALSE otherwise. 
  1467.  
  1468. Notes 
  1469.  
  1470. Use CmnFilSetExtAttribute to write an extended attribute to a file.  Since this 
  1471. function enforces the convention stated in the IBM Programming Toolkit's 
  1472. "Programming Guide", you should use CmnFilQueryExtAttribute to read the 
  1473. extended attribute when needed or insure that the code is aware of the added 
  1474. information written. 
  1475.  
  1476. Related information 
  1477.  
  1478. If an FEA_ constant is specified for pchVendor, pchAppl and pchName are 
  1479. ignored. 
  1480.  
  1481. o FEA_ constants 
  1482. o CmnFilQueryExtAttribute 
  1483.  
  1484.  
  1485. ΓòÉΓòÉΓòÉ 7.9. CmnFilSplitFilename ΓòÉΓòÉΓòÉ
  1486.  
  1487. CmnFilSplitFilename 
  1488.  
  1489. Purpose 
  1490.  
  1491. This function splits a filename into its various components. 
  1492.  
  1493. Syntax 
  1494.  
  1495. (BOOL)CmnFilSplitFilename(pchFile,pchDrive,pchPath,pchName);
  1496.  
  1497. Parameters 
  1498.  
  1499. pchFile (PCHAR) - points to the name of the file to be split 
  1500.  
  1501. pchDrive (PCHAR) - points to the buffer to receive the drive 
  1502.  
  1503. pchPath (PCHAR) - points to the buffer to receive the path 
  1504.  
  1505. pchName (PCHAR) - points to the buffer to receive the name 
  1506.  
  1507. Returns 
  1508.  
  1509. This function returns TRUE if successful, or FALSE otherwise. 
  1510.  
  1511. Notes 
  1512.  
  1513. pchDrive, pchPath, or pchName can be NULL if you are not interested in that 
  1514. component. 
  1515.  
  1516. pchDrive will always end in a colon (':'). 
  1517.  
  1518. pchPath will always end with a backslash ('\'). 
  1519.  
  1520.  
  1521. ΓòÉΓòÉΓòÉ 8. Link-list routines ΓòÉΓòÉΓòÉ
  1522.  
  1523. The purpose of this group is to provide a complete linked list implementation 
  1524. which is limited only by the amount of memory in your system. I have defined a 
  1525. list to be a set of homogeneous items; thus, each item in the list is of a 
  1526. fixed size, which is declared when the list is created.  Also, each item is 
  1527. doubly linked to provide quick access to any record from anywhere in the list. 
  1528. While this imposes an extra four bytes per record, the performance gains 
  1529. outweigh the additional memory required. 
  1530.  
  1531. Note that the links are hidden from the record; this is good in that if you 
  1532. want to have a list of integers, you do not have to define a structure to hold 
  1533. the integer and the links.  Additionally, this hides the implementation of the 
  1534. list from the developer, so if it changes (and it has before) the developer 
  1535. does not need to do anything other than recompile. 
  1536.  
  1537. Listed below are the functions which comprise this group: 
  1538.  
  1539. o CmnLstAddRecord 
  1540. o CmnLstAddUniqueRecord 
  1541. o CmnLstCopyList 
  1542. o CmnLstCreateList 
  1543. o CmnLstDeleteList 
  1544. o CmnLstDeleteRecord 
  1545. o CmnLstDestroyList 
  1546. o CmnLstMoveRecord 
  1547. o CmnLstPruneList 
  1548. o CmnLstQueryRecord 
  1549. o CmnLstQueryRecordCount 
  1550. o CmnLstQueryRelative 
  1551. o CmnLstQuickSortList 
  1552. o CmnLstSearchRecord 
  1553. o CmnLstSortList 
  1554. o CmnLstTraverseList 
  1555.  
  1556.  
  1557. ΓòÉΓòÉΓòÉ 8.1. CmnLstAddRecord ΓòÉΓòÉΓòÉ
  1558.  
  1559. CmnLstAddRecord 
  1560.  
  1561. Purpose 
  1562.  
  1563. This function adds a record to a linked list. 
  1564.  
  1565. Syntax 
  1566.  
  1567. (BOOL)CmnLstAddRecord(hclList,pvRecord,pfnSort,ppvResult);
  1568.  
  1569. Parameters 
  1570.  
  1571. hclList (HCLLIST) - handle of the linked list to add to. 
  1572.  
  1573. pvRecord (PVOID) - points to the record to add. 
  1574.  
  1575. pfnSort (PFNRECCOMP) - points to the function which defines the sort order or 
  1576. an LAR_ constant. 
  1577.  
  1578. ppvResult (PVOID *) - points to the variable which receives the pointer to the 
  1579. inserted record. 
  1580.  
  1581. Returns 
  1582.  
  1583. This function returns TRUE if successful, or FALSE otherwise. 
  1584.  
  1585. Notes 
  1586.  
  1587. Use CmnLstAddRecord to add a record to a linked list in the order defined by 
  1588. pfnSort.  Since the linked list routines maintain their own copy of the 
  1589. records, ppvResult can optionally be specified to receive the pointer to the 
  1590. record within the list. pfnSort either points to a function which defines the 
  1591. placement of the record within the list or specifies an LAR_ constant. 
  1592.  
  1593. Note that if uniqueness must be enforced, you should instead use 
  1594. CmnLstAddUniqueRecord. 
  1595.  
  1596. Related information 
  1597.  
  1598. o LAR_ constants 
  1599. o HCLLIST data type 
  1600. o PFNRECCOMP function 
  1601. o CmnLstAddUniqueRecord 
  1602.  
  1603.  
  1604. ΓòÉΓòÉΓòÉ 8.2. CmnLstAddUniqueRecord ΓòÉΓòÉΓòÉ
  1605.  
  1606. CmnLstAddUniqueRecord 
  1607.  
  1608. Purpose 
  1609.  
  1610. This function adds a record to a linked list only if it did not exist 
  1611. previously. 
  1612.  
  1613. Syntax 
  1614.  
  1615. (USHORT)CmnLstAddUniqueRecord(hclList,
  1616.                               pvRecord,
  1617.                               pfnSearch,
  1618.                               pfnSort,
  1619.                               ppvResult);
  1620.  
  1621. Parameters 
  1622.  
  1623. hclList (HCLLIST) - handle of the linked list to add to. 
  1624.  
  1625. pvRecord (PVOID) - points to the record to add. 
  1626.  
  1627. pfnSearch (PFNRECCOMP) - points to the function which determines the equality 
  1628. of two records. 
  1629.  
  1630. pfnSort (PFNRECCOMP) - points to the function which defines the sort order. 
  1631.  
  1632. ppvResult (PVOID *) - points to the variable which receives the pointer to the 
  1633. inserted record. 
  1634.  
  1635. Returns 
  1636.  
  1637. This function returns LAUR_NOERROR if successful, LAUR_EXISTS if the record 
  1638. existed in the list prior to this call, or LAUR_ERROR if an error occurred. 
  1639.  
  1640. Notes 
  1641.  
  1642. Use CmnLstAddUniqueRecord to add a record in a linked list, while guaranteeing 
  1643. uniqueness within the list.  Since the linked list routines maintain their own 
  1644. copy of the records, ppvResult can optionally be specified to receive the 
  1645. pointer to the record within the list. pfnSort either points to a function 
  1646. which defines the placement of the record within the list or specifies an LAR_ 
  1647. constant. pnfSearch points to a function which determines whether or not two 
  1648. records are equal and is required. 
  1649.  
  1650. Related information 
  1651.  
  1652. o LAR_ constants 
  1653. o HCLLIST data type 
  1654. o PFNRECCOMP function 
  1655.  
  1656.  
  1657. ΓòÉΓòÉΓòÉ 8.3. CmnLstCopyList ΓòÉΓòÉΓòÉ
  1658.  
  1659. CmnLstCopyList 
  1660.  
  1661. Purpose 
  1662.  
  1663. This function copies the contents of one list into another list. 
  1664.  
  1665. Syntax 
  1666.  
  1667. (BOOL)CmnLstCopyList(hclList,hclCopy,pfnSort);
  1668.  
  1669. Parameters 
  1670.  
  1671. hclList (HCLLIST) - handle of the linked list to copy to. 
  1672.  
  1673. hclCopy (HCLLIST) - handle of the linked list to copy from. 
  1674.  
  1675. pfnSort (PFNRECCOMP) - points to the function which defines the sort order. 
  1676.  
  1677. Returns 
  1678.  
  1679. This function returns TRUE if successful, or FALSE otherwise. 
  1680.  
  1681. Notes 
  1682.  
  1683. Use CmnLstCopyList to copy the contents of one list into another.  While this 
  1684. can be used to append a list to another, this function is frequently used to 
  1685. simply copy a list so that modifications to the original list can be recovered. 
  1686.  
  1687. Related information 
  1688.  
  1689. o HCLLIST data type 
  1690.  
  1691.  
  1692. ΓòÉΓòÉΓòÉ 8.4. CmnLstCreateList ΓòÉΓòÉΓòÉ
  1693.  
  1694. CmnLstCreateList 
  1695.  
  1696. Purpose 
  1697.  
  1698. This function creates a linked list handle for use in subsequent calls to the 
  1699. CmnLst functions. 
  1700.  
  1701. Syntax 
  1702.  
  1703. (BOOL)CmnLstCreateList(usSzRecord,phclList);
  1704.  
  1705. Parameters 
  1706.  
  1707. usSzRecord (USHORT) - specifies the size of each record in the linked list. 
  1708.  
  1709. phclList (PHCLLIST) - points to the variable which receives the created linked 
  1710. list handle. 
  1711.  
  1712. Returns 
  1713.  
  1714. This function returns TRUE if successful, or FALSE otherwise. 
  1715.  
  1716. Notes 
  1717.  
  1718. Use CmnLstCreateList to create a linked list handle which can be used in other 
  1719. CmnLst functions.  Note that only linked lists of fixed record size are 
  1720. supported, although specifying the maximum size of any record and then storing 
  1721. the actual size in the record itself would work (albeit very 
  1722. memory-inefficient). 
  1723.  
  1724. Since the records do not contain the link information directly, do not specify 
  1725. this in usSzRecord. 
  1726.  
  1727. Related information 
  1728.  
  1729. o HCLLIST data type 
  1730. o CmnLstDestroyList 
  1731.  
  1732.  
  1733. ΓòÉΓòÉΓòÉ 8.5. CmnLstDeleteList ΓòÉΓòÉΓòÉ
  1734.  
  1735. CmnLstDeleteList 
  1736.  
  1737. Purpose 
  1738.  
  1739. This function deletes the contents of a linked list. 
  1740.  
  1741. Syntax 
  1742.  
  1743. (BOOL)CmnLstDeleteList(hclList);
  1744.  
  1745. Parameters 
  1746.  
  1747. hclList (HCLLIST) - handle of the linked list to delete. 
  1748.  
  1749. Returns 
  1750.  
  1751. This function returns TRUE if successful, or FALSE otherwise. 
  1752.  
  1753. Notes 
  1754.  
  1755. Use CmnLstDeleteList to delete the contents of a linked list. Note that the 
  1756. list still "exists" after this call; it is simply emptied of its contents.  To 
  1757. destroy a list, use CmnLstDestroyList. 
  1758.  
  1759. Related information 
  1760.  
  1761. o HCLLIST data type 
  1762. o CmnLstDestroyList 
  1763.  
  1764.  
  1765. ΓòÉΓòÉΓòÉ 8.6. CmnLstDeleteRecord ΓòÉΓòÉΓòÉ
  1766.  
  1767. CmnLstDeleteRecord 
  1768.  
  1769. Purpose 
  1770.  
  1771. This function deletes a record from a linked list. 
  1772.  
  1773. Syntax 
  1774.  
  1775. (BOOL)CmnLstDeleteRecord(hclList,pvRecord);
  1776.  
  1777. Parameters 
  1778.  
  1779. hclList (HCLLIST) - handle of the linked list to delete from. 
  1780.  
  1781. pvRecord (PVOID) - points to the record to delete. 
  1782.  
  1783. Returns 
  1784.  
  1785. This function returns TRUE if successful, or FALSE otherwise. 
  1786.  
  1787. Notes 
  1788.  
  1789. Use CmnLstDeleteRecord to delete a specific record from a linked list.  This 
  1790. function adjusts the links in the list and frees the memory consumed by the 
  1791. record (but does not free any memory which is pointed to by any fields in the 
  1792. record).  To delete the entire list, use CmnLstDeleteList. 
  1793.  
  1794. Related information 
  1795.  
  1796. o HCLLIST data type 
  1797. o CmnLstDeleteList 
  1798.  
  1799.  
  1800. ΓòÉΓòÉΓòÉ 8.7. CmnLstDestroyList ΓòÉΓòÉΓòÉ
  1801.  
  1802. CmnLstDestroyList 
  1803.  
  1804. Purpose 
  1805.  
  1806. This function deletes the contents of a linked list and destroys the handle to 
  1807. the linked list. 
  1808.  
  1809. Syntax 
  1810.  
  1811. (BOOL)CmnLstDestroyList(phclList);
  1812.  
  1813. Parameters 
  1814.  
  1815. phclList (PHCLLIST) - points to the variable specifying the handle of the 
  1816. linked list to delete.  On return, this variable contains NULL. 
  1817.  
  1818. Returns 
  1819.  
  1820. This function returns TRUE if successful, or FALSE otherwise. 
  1821.  
  1822. Notes 
  1823.  
  1824. Use CmnLstDestroyList to destroy a linked list handle.  All records are delete 
  1825. via a call to CmnLstDeleteList before destroying the handle. 
  1826.  
  1827. Related information 
  1828.  
  1829. o HCLLIST data type 
  1830. o CmnLstCreateList 
  1831. o CmnLstDeleteList 
  1832.  
  1833.  
  1834. ΓòÉΓòÉΓòÉ 8.8. CmnLstMoveRecord ΓòÉΓòÉΓòÉ
  1835.  
  1836. CmnLstMoveRecord 
  1837.  
  1838. Purpose 
  1839.  
  1840. This function moves a record to a position relative to another record. 
  1841.  
  1842. Syntax 
  1843.  
  1844. (BOOL)CmnLstMoveRecord(hclList,pvMove,pvWhere,sRelative);
  1845.  
  1846. Parameters 
  1847.  
  1848. hclList (HCLLIST) - handle of the linked list. 
  1849.  
  1850. pvMove (PVOID) - pointer to the record to move 
  1851.  
  1852. pvWhere (PVOID) - pointer to the record specifying the new location 
  1853.  
  1854. sRelative (SHORT) - either LQR_PREVIOUS or LQR_NEXT specifying immediately 
  1855. before or after pvWhere, respectively. 
  1856.  
  1857. Returns 
  1858.  
  1859. This function returns TRUE if successful, or FALSE otherwise. 
  1860.  
  1861. Notes 
  1862.  
  1863. Use CmnLstMoveRecord to move a record before or after another record in a 
  1864. linked list. 
  1865.  
  1866. Related information 
  1867.  
  1868. o HCLLIST data type 
  1869.  
  1870.  
  1871. ΓòÉΓòÉΓòÉ 8.9. CmnLstPruneList ΓòÉΓòÉΓòÉ
  1872.  
  1873. CmnLstPruneList 
  1874.  
  1875. Purpose 
  1876.  
  1877. This function traverses a linked list and deletes the records that meet the 
  1878. specified criteria. 
  1879.  
  1880. Syntax 
  1881.  
  1882. (BOOL)CmnLstPruneList(hclList,pvRecord,pfnSearch);
  1883.  
  1884. hclList (HCLLIST) - handle of the linked list to prune. 
  1885.  
  1886. pvSearch (PVOID) - points to a buffer specifying the search criteria.  This is 
  1887. passed to pfnSearch as the second parameter. 
  1888.  
  1889. pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a 
  1890. record matches the criteria. 
  1891.  
  1892. Returns 
  1893.  
  1894. This function returns TRUE if successful, or FALSE otherwise. 
  1895.  
  1896. Notes 
  1897.  
  1898. Use CmnLstPruneList to remove only those records which meet a specific set of 
  1899. criteria from a linked list.  This is typically used after calling 
  1900. CmnLstCopyList to remove all but the records of interest from the copied list. 
  1901.  
  1902. Related information 
  1903.  
  1904. o HCLLIST data type 
  1905. o PFNRECCOMP function 
  1906. o CmnLstSearchRecord 
  1907.  
  1908.  
  1909. ΓòÉΓòÉΓòÉ 8.10. CmnLstQueryRecord ΓòÉΓòÉΓòÉ
  1910.  
  1911. CmnLstQueryRecord 
  1912.  
  1913. Purpose 
  1914.  
  1915. This function returns a pointer to the specified element in a linked list. 
  1916.  
  1917. Syntax 
  1918.  
  1919. (PVOID)CmnLstQueryRecord(hclList,sNumRecord);
  1920.  
  1921. Parameters 
  1922.  
  1923. hclList (HCLLIST) - handle of the linked list to query. 
  1924.  
  1925. sNumRecord (SHORT) - specifies the 0-based index of the record desired. 
  1926.  
  1927. Returns 
  1928.  
  1929. This function returns a pointer to the desired record if successful, or NULL 
  1930. otherwise. 
  1931.  
  1932. Notes 
  1933.  
  1934. Use CmnLstQueryRecord to query a specific record number from a linked list. 
  1935. Note that, if the record desired precedes or follows a previously queried 
  1936. record, it is much more efficient to instead use CmnLstQueryRelative.  This is 
  1937. an especially prominent condition in loop-based processing: 
  1938.  
  1939. usNumRecs=CmnLstQueryRecordCount(hclList);
  1940. for (usIndex=0; usIndex<usNumRecs; usIndex++) {
  1941.    prRecord=CmnLstQueryRecord(hclList,usIndex);
  1942.       :
  1943. } /* endfor */
  1944. should instead be coded as 
  1945.  
  1946. usNumRecs=CmnLstQueryRecordCount(hclList);
  1947. for (usIndex=0; usIndex<usNumRecs; usIndex++) {
  1948.    if (usIndex==0) {
  1949.       prRecord=CmnLstQueryRecord(hclList,0);
  1950.    } else {
  1951.       prRecord=CmnLstQueryRelative(prRecord,LQR_NEXT);
  1952.    } /* endif */
  1953.       :
  1954. } /* endfor */
  1955.  
  1956. Related information 
  1957.  
  1958. o HCLLIST data type 
  1959. o CmnLstQueryRelative 
  1960.  
  1961.  
  1962. ΓòÉΓòÉΓòÉ 8.11. CmnLstQueryRecordCount ΓòÉΓòÉΓòÉ
  1963.  
  1964. CmnLstQueryRecordCount 
  1965.  
  1966. Purpose 
  1967.  
  1968. This function queries the number of records in a linked list. 
  1969.  
  1970. Syntax 
  1971.  
  1972. (SHORT)CmnLstQueryRecordCount(hclList);
  1973.  
  1974. Parameters 
  1975.  
  1976. hclList (HCLLIST) - handle of the linked list to query. 
  1977.  
  1978. Returns 
  1979.  
  1980. This function returns the number of records in the linked list if successful, 
  1981. or LQRC_ERROR otherwise. 
  1982.  
  1983. Notes 
  1984.  
  1985. Use CmnLstQueryRecordCount to query the number of records in a linked list. 
  1986. Note that this call is expensive in terms of execution time, so it should not 
  1987. be used as the terminating condition of a loop.  Instead, store the number of 
  1988. records in a local variable prior to entering the loop and use the variable 
  1989. instead.  For example, 
  1990.  
  1991. for (usIndex=0; usIndex<CmnLstQueryRecordCount(hclList); usIndex++) {
  1992.    :
  1993. } /* endfor */
  1994. should instead be coded as 
  1995.  
  1996. usNumRecs=CmnLstQueryRecordCount(hclList);
  1997. for (usIndex=0; usIndex<usNumRecs; usIndex++) {
  1998.    :
  1999. } /* endfor */
  2000.  
  2001. Related information 
  2002.  
  2003. o HCLLIST data type 
  2004.  
  2005.  
  2006. ΓòÉΓòÉΓòÉ 8.12. CmnLstQueryRelative ΓòÉΓòÉΓòÉ
  2007.  
  2008. CmnLstQueryRelative 
  2009.  
  2010. Purpose 
  2011.  
  2012. This function queries either the previous or the next record from a specified 
  2013. record. 
  2014.  
  2015. Syntax 
  2016.  
  2017. (PVOID)CmnLstQueryRelative(pvRecord,sWhich);
  2018.  
  2019. Parameters 
  2020.  
  2021. pvRecord (PVOID) - points to the record to query. 
  2022.  
  2023. sWhich (SHORT) - specifies an LQR_ constant. 
  2024.  
  2025. Returns 
  2026.  
  2027. This function returns the relative record if successful, or NULL if the record 
  2028. prior to the head of the list or record following the tail of the list was 
  2029. specified or an error occurred. 
  2030.  
  2031. Notes 
  2032.  
  2033. Use CmnLstQueryRelative to query either the previous or the next record from a 
  2034. specified record.  While this call is very fast, it does not attempt to 
  2035. validate that the record actually belongs to any list; this responsibility is 
  2036. left to the programmer. 
  2037.  
  2038. Related information 
  2039.  
  2040. o LQR_ constants 
  2041. o HCLLIST data type 
  2042.  
  2043.  
  2044. ΓòÉΓòÉΓòÉ 8.13. CmnLstQuickSortList ΓòÉΓòÉΓòÉ
  2045.  
  2046. CmnLstQuickSortList 
  2047.  
  2048. Purpose 
  2049.  
  2050. This function sorts a linked list using a version of the "quick sort" algorithm 
  2051. modified for use with linked lists. 
  2052.  
  2053. Syntax 
  2054.  
  2055. (BOOL)CmnLstQuickSortList(hclList,pfnMedian,pfnCompare);
  2056.  
  2057. Parameters 
  2058.  
  2059. hclList (HCLLIST) - handle of the list to sort. 
  2060.  
  2061. pfnMedian (PFNRECMED) - points to the function which defines the median of the 
  2062. list. 
  2063.  
  2064. pfnCompare (PFNRECCOMP) - points to the function which determines whether or 
  2065. not two records are equal. 
  2066.  
  2067. Returns 
  2068.  
  2069. This function returns TRUE if successful, or FALSE otherwise. 
  2070.  
  2071. Notes 
  2072.  
  2073. Use CmnLstQuickSortList to quickly sort a linked list. Unfortunately, since the 
  2074. records of the linked list are rarely in a contiguous block of memory, this 
  2075. function is not as quick as would be expected, although it is much faster than 
  2076. using CmnLstSortList, which uses a bubble-sort implementation. 
  2077.  
  2078. This speed does not come without its downside - this function consumes a lot of 
  2079. both stack space (due to the recursive nature of the algorithm) and heap space 
  2080. (since each partition must be stored in a temporary list). 
  2081.  
  2082. Related information 
  2083.  
  2084. o HCLLIST data type 
  2085. o PFNRECMED function 
  2086. o PFNRECCOMP function 
  2087.  
  2088.  
  2089. ΓòÉΓòÉΓòÉ 8.14. CmnLstSearchRecord ΓòÉΓòÉΓòÉ
  2090.  
  2091. CmnLstSearchRecord 
  2092.  
  2093. Purpose 
  2094.  
  2095. This function searches a linked list for a record which matches the search 
  2096. criteria. 
  2097.  
  2098. Syntax 
  2099.  
  2100. (PVOID)CmnLstSearchRecord(pvRecord,pvSearch,pfnSearch);
  2101.  
  2102. Parameters 
  2103.  
  2104. pvRecord (PVOID) - points to the first record to begin searching with. 
  2105.  
  2106. pvSearch (PVOID) - points to a buffer specifying the search criteria.  This is 
  2107. passed to pfnSearch as the second parameter. 
  2108.  
  2109. pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a 
  2110. record matches the criteria. 
  2111.  
  2112. Returns 
  2113.  
  2114. This function returns a pointer to the first record on or after pvRecord which 
  2115. matches the search criteria if successful, or NULL otherwise. 
  2116.  
  2117. Notes 
  2118.  
  2119. Use CmnLstSearchRecord to search a linked list for records matching specified 
  2120. search criteria.  Typically, pvSearch is simply a pointer to a record of the 
  2121. same type that comprises the linked list with the pertinet fields initialized 
  2122. to the values to be compared against every record on or after pvRecord. 
  2123. pfnSearch then compares these fields and returns the appropriate value. 
  2124.  
  2125. Related information 
  2126.  
  2127. o HCLLIST data type 
  2128. o PFNRECCOMP function 
  2129.  
  2130.  
  2131. ΓòÉΓòÉΓòÉ 8.15. CmnLstSortList ΓòÉΓòÉΓòÉ
  2132.  
  2133. CmnLstSortList 
  2134.  
  2135. Purpose 
  2136.  
  2137. This function sorts a linked list using a version of the "bubble" sort 
  2138. algorithm modified for use with linked lists. 
  2139.  
  2140. Syntax 
  2141.  
  2142. (BOOL)CmnLstSortList(hclList,pfnSort);
  2143.  
  2144. Parameters 
  2145.  
  2146. hclList (HCLLIST) - handle of the list to sort. 
  2147.  
  2148. pfnSort (PFNRECCOMP) - points to the function which determines whether or not 
  2149. two records are equal. 
  2150.  
  2151. Returns 
  2152.  
  2153. This function returns TRUE if successful, or FALSE otherwise. 
  2154.  
  2155. Notes 
  2156.  
  2157. Use CmnLstSortList to sort a linked list.  Although no extra resources are 
  2158. consumed (with the exception of stack space for local variables), the algorithm 
  2159. is extremely slow.  For sorts that require less time (and are not concerned 
  2160. with the consumption of resources), use CmnLstQuickSortList instead. 
  2161.  
  2162. Related information 
  2163.  
  2164. o HCLLIST data type 
  2165. o PFNRECCOMP function 
  2166. o CmnLstQuickSortList 
  2167.  
  2168.  
  2169. ΓòÉΓòÉΓòÉ 8.16. CmnLstTraverseList ΓòÉΓòÉΓòÉ
  2170.  
  2171. CmnLstTraverseList 
  2172.  
  2173. Purpose 
  2174.  
  2175. This function traverses a linked list. 
  2176.  
  2177. Syntax 
  2178.  
  2179. (BOOL)CmnLstTraverseList(hclList,pfnFunc);
  2180.  
  2181. Parameters 
  2182.  
  2183. hclList (HCLLIST) - handle of the list to traverse. 
  2184.  
  2185. pfnFunc (PFNRECFUNC) - points to a function which is called for each record in 
  2186. the linked list. 
  2187.  
  2188. Returns 
  2189.  
  2190. This function returns TRUE if successful, or FALSE otherwise. 
  2191.  
  2192. Notes 
  2193.  
  2194. Use CmnLstTraverseList to traverse a linked list for debugging purposes.  For 
  2195. every record in the linked list, pfnFunc is called, giving the application the 
  2196. ability to write the contents of the record to the screen, a file, a 
  2197. communication port, etc..  When used in conjunction with CmnDbgWriteRecord, a 
  2198. linked list dump can be easily generated with minimal code. 
  2199.  
  2200. Related information 
  2201.  
  2202. o HCLLIST data type 
  2203. o PFNRECFUNC function 
  2204. o CmnDbgWriteRecord 
  2205.  
  2206.  
  2207. ΓòÉΓòÉΓòÉ 9. Memory allocation routines ΓòÉΓòÉΓòÉ
  2208.  
  2209. The purpose of this group is to provide memory allocation routines which are 
  2210. easy to use and provide functionality above that provided by the C run-time 
  2211. library.  The routines use the DosSubAlloc and DosSubFree kernel functions for 
  2212. the suballocation of the individual heaps, so there are no free lists that are 
  2213. maintained by these routines (less code means less bugs). 
  2214.  
  2215. A useful function is the CmnQueryHandleInfo function which returns the total 
  2216. amount of memory in use by a memory manager handle. 
  2217.  
  2218. Listed below are the functions which comprise this group: 
  2219.  
  2220. o CmnMemAllocate 
  2221. o CmnMemFree 
  2222. o CmnMemInitialize 
  2223. o CmnMemQueryMemSize 
  2224. o CmnMemReset 
  2225. o CmnMemTerminate 
  2226.  
  2227.  
  2228. ΓòÉΓòÉΓòÉ 9.1. CmnMemAllocate ΓòÉΓòÉΓòÉ
  2229.  
  2230. CmnMemAllocate 
  2231.  
  2232. Purpose 
  2233.  
  2234. This function allocates a block of memory of a specified size. 
  2235.  
  2236. Syntax 
  2237.  
  2238. (MEMERROR)CmnMemAllocate(hcmMem,ulSzBuf,ppvBuf);
  2239.  
  2240. Parameters 
  2241.  
  2242. hcmMem (HCMMEM) - handle of the memory manager instance. 
  2243.  
  2244. ulSzBuf (ULONG) - specifies the size of the memory block requested. 
  2245.  
  2246. ppvBuf (PVOID *) - points to the variable which receives the pointer to the 
  2247. allocated memory. 
  2248.  
  2249. Returns 
  2250.  
  2251. This function returns one of the following values: 
  2252.  
  2253. MEM_ERR_NOERROR 
  2254. MEM_ERR_BADHANDLE 
  2255. MEM_ERR_NOMEMORY 
  2256. MEM_ERR_SIZETOOLARGE 
  2257.  
  2258. Notes 
  2259.  
  2260. The algorithm used by the function is to attempt to allocate the specified 
  2261. amount of memory from those heaps which already are being used.  If the request 
  2262. cannot be satisfied and there is at least one heap slot that is not in use, 
  2263. then a new heap is created and the memory requested is allocated from the new 
  2264. heap. 
  2265.  
  2266. Related information 
  2267.  
  2268. o HCMMEM data type 
  2269. o CmnMemFree 
  2270. o CmnMemReset 
  2271.  
  2272.  
  2273. ΓòÉΓòÉΓòÉ 9.2. CmnMemFree ΓòÉΓòÉΓòÉ
  2274.  
  2275. CmnMemFree 
  2276.  
  2277. Purpose 
  2278.  
  2279. This function frees a block of memory previously allocated with CmnMemAllocate. 
  2280.  
  2281. Syntax 
  2282.  
  2283. (MEMERROR)CmnMemFree(hcmMem,pvBuf);
  2284.  
  2285. Parameters 
  2286.  
  2287. hcmMem (HCMMEM) - handle of the memory manager instance. 
  2288.  
  2289. pvBuf (PVOID) - pointer to the memory block to free 
  2290.  
  2291. Returns 
  2292.  
  2293. This function returns one of the following values: 
  2294.  
  2295. MEM_ERR_NOERROR 
  2296. MEM_ERR_BADHANDLE 
  2297. MEM_ERR_BADPOINTER 
  2298. MEM_ERR_ERROR 
  2299.  
  2300. Notes 
  2301.  
  2302. Because of the dynamic committal strategy used by the memory routines, a 
  2303. reference count is maintained for each heap that is in use and it is updated 
  2304. whenever either CmnMemAllocate or CmnMemFree is called. When this function 
  2305. determines that the reference count is zero, it deallocates the memory used by 
  2306. the heap and marks the heap as "empty". 
  2307.  
  2308. Related information 
  2309.  
  2310. o HCMMEM data type 
  2311. o CmnMemAllocate 
  2312. o CmnMemReset 
  2313.  
  2314.  
  2315. ΓòÉΓòÉΓòÉ 9.3. CmnMemInitialize ΓòÉΓòÉΓòÉ
  2316.  
  2317. CmnMemInitialize 
  2318.  
  2319. Purpose 
  2320.  
  2321. This function creates an instance of the memory manager. 
  2322.  
  2323. Syntax 
  2324.  
  2325. (MEMERROR)CmnMemInitialize(pcmiInfo,phcmMem);
  2326.  
  2327. Parameters 
  2328.  
  2329. pcmiInfo (PCMMEMINFO) - points to a CMMEMINFO structure which describes the 
  2330. desired characteristics of the instance.  If NULL, the defaults are used (see 
  2331. below). 
  2332.  
  2333. phcmMem (PHCMMEM) - points to the variable which receives the created instance 
  2334. of the memory manager. 
  2335.  
  2336. Returns 
  2337.  
  2338. This function returns one of the following values: 
  2339.  
  2340. MEM_ERR_NOERROR 
  2341. MEM_ERR_NOMEMORY 
  2342.  
  2343. Notes 
  2344.  
  2345. The heaps are subdivided by the CmnMemAllocate and CmnMemFree routines using 
  2346. the DosSubAlloc and DosSubFree APIs.  Allowing for housekeeping data kept by 
  2347. both the system and the memory manager, the amount of allocatable memory will 
  2348. be less than the value of ulSzHeaps (how much less depends on the number of 
  2349. allocations have been made from a particular heap). 
  2350.  
  2351. Related information 
  2352.  
  2353. o HCMMEM data type 
  2354. o CMMEMINFO data type 
  2355. o CmnMemReset 
  2356. o CmnMemTerminate 
  2357.  
  2358.  
  2359. ΓòÉΓòÉΓòÉ 9.4. CmnMemQueryMemSize ΓòÉΓòÉΓòÉ
  2360.  
  2361. CmnMemQueryMemSize 
  2362.  
  2363. Purpose 
  2364.  
  2365. This function returns the size of the specified memory block. 
  2366.  
  2367. Syntax 
  2368.  
  2369. (ULONG)CmnMemQueryMemSize(pvBuf);
  2370.  
  2371. Parameters 
  2372.  
  2373. pvBuf (PVOID) - points to a memory block previously allocated by 
  2374. CmnMemAllocate. 
  2375.  
  2376. Returns 
  2377.  
  2378. This function returns the size of the memory block specified. 
  2379.  
  2380. Notes 
  2381.  
  2382. This function does no validity checks to insure that pvBuf was indeed allocated 
  2383. with CmnMemAllocate. 
  2384.  
  2385. Related information 
  2386.  
  2387. o CmnMemAllocate 
  2388.  
  2389.  
  2390. ΓòÉΓòÉΓòÉ 9.5. CmnMemReset ΓòÉΓòÉΓòÉ
  2391.  
  2392. CmnMemReset 
  2393.  
  2394. Purpose 
  2395.  
  2396. This function resets the specified instance of the memory manager to its 
  2397. initial state. 
  2398.  
  2399. Syntax 
  2400.  
  2401. (MEMERROR)CmnMemReset(hcmMem);
  2402.  
  2403. Parameters 
  2404.  
  2405. hcmMem (HCMMEM) - handle of the memory manager instance. 
  2406.  
  2407. Returns 
  2408.  
  2409. This function returns one of the following values: 
  2410.  
  2411. MEM_ERR_NOERROR 
  2412. MEM_ERR_BADHANDLE 
  2413.  
  2414. Notes 
  2415.  
  2416. This function returns all memory to the system and reinitializes all of the 
  2417. internal heaps to the "empty" state. 
  2418.  
  2419. Related information 
  2420.  
  2421. o HCMMEM data type 
  2422. o CmnMemInitialize 
  2423. o CmnMemTerminate 
  2424.  
  2425.  
  2426. ΓòÉΓòÉΓòÉ 9.6. CmnMemTerminate ΓòÉΓòÉΓòÉ
  2427.  
  2428. CmnMemTerminate 
  2429.  
  2430. Purpose 
  2431.  
  2432. This function destroys the specified instance of the memory manager. 
  2433.  
  2434. Syntax 
  2435.  
  2436. (MEMERROR)CmnMemTerminate(phcmMem);
  2437.  
  2438. Parameters 
  2439.  
  2440. phcmMem (PHCMMEM) - points to the variable specifying the handle of the memory 
  2441. manager instance to destroy.  On return, this contains NULL. 
  2442.  
  2443. Returns 
  2444.  
  2445. This function returns one of the following values: 
  2446.  
  2447. MEM_ERR_NOERROR 
  2448. MEM_ERR_BADHANDLE 
  2449. MEM_ERR_ERROR 
  2450.  
  2451. Notes 
  2452.  
  2453. This function first calls CmnMemReset to return all allocated memory to the 
  2454. system. 
  2455.  
  2456. Related information 
  2457.  
  2458. o HCMMEM data type 
  2459. o CmnMemInitialize 
  2460. o CmnMemReset 
  2461.  
  2462.  
  2463. ΓòÉΓòÉΓòÉ 10. Object handling routines ΓòÉΓòÉΓòÉ
  2464.  
  2465. The purpose of this group is to provide object handling routines.  An "object" 
  2466. is an abstract concept that is defined by an application.  No structure is 
  2467. imposed on the objects except with regards to their names. Because of this, the 
  2468. APIs are limited in the functionality they can provide. 
  2469.  
  2470. I have hopes of modifying this group to allow for objects that are distributed 
  2471. across a network, but am not sure that I will have the time or the resources to 
  2472. fulfill this vision. 
  2473.  
  2474. Listed below are the functions which comprise this group: 
  2475.  
  2476. o CmnObjCreateObject 
  2477. o CmnObjDestroyObject 
  2478. o CmnObjInitialize 
  2479. o CmnObjObjectFromName 
  2480. o CmnObjQueryObject 
  2481. o CmnObjQueryObjectData 
  2482. o CmnObjReset 
  2483. o CmnObjSetObjectData 
  2484. o CmnObjTerminate 
  2485.  
  2486.  
  2487. ΓòÉΓòÉΓòÉ 10.1. CmnObjCreateObject ΓòÉΓòÉΓòÉ
  2488.  
  2489. CmnObjCreateObject 
  2490.  
  2491. Purpose 
  2492.  
  2493. This function creates a new object. 
  2494.  
  2495. Syntax 
  2496.  
  2497. (OBJERROR)CmnObjCreateObject(hcoParent,pchName,phcoResult)
  2498.  
  2499. Parameters 
  2500.  
  2501. hcoParent (HCOOBJECT) - handle of the parent object. 
  2502.  
  2503. pchName (PCHAR) - points to the desired subname of the object. 
  2504.  
  2505. phcoResult (PHCOOBJECT) - points to the variable that receives the newly 
  2506. created object handle. 
  2507.  
  2508. Returns 
  2509.  
  2510. This function returns one of the following values: 
  2511.  
  2512. OBJ_ERR_NOERROR 
  2513. OBJ_ERR_BADARGUMENT 
  2514. OBJ_ERR_BADHANDLE 
  2515. OBJ_ERR_BADNAME 
  2516. OBJ_ERR_INITFAILED 
  2517. OBJ_ERR_NOMEMORY 
  2518. OBJ_ERR_NOTROOT 
  2519.  
  2520. Notes 
  2521.  
  2522. Use CmnObjCreateObject to create a new object whose parent is specified by 
  2523. hcoParent.  The "subname" can contain any characters except backslashes (see 
  2524. CmnObjObjectFromName). 
  2525.  
  2526. Related information 
  2527.  
  2528. o HCOOBJECT data type 
  2529. o CmnObjDestroyObject 
  2530.  
  2531.  
  2532. ΓòÉΓòÉΓòÉ 10.2. CmnObjDestroyObject ΓòÉΓòÉΓòÉ
  2533.  
  2534. CmnObjDestroyObject 
  2535.  
  2536. Purpose 
  2537.  
  2538. This function destroys an object. 
  2539.  
  2540. Syntax 
  2541.  
  2542. (OBJERROR)CmnObjDestroyObject(phcoObject)
  2543.  
  2544. Parameters 
  2545.  
  2546. phcoObject (PHCOOBJECT) - points to the variable specifying the handle of the 
  2547. object to destroy.  On return, this variable contains NULL 
  2548.  
  2549. Returns 
  2550.  
  2551. This function returns one of the following values: 
  2552.  
  2553. OBJ_ERR_NOERROR 
  2554. OBJ_ERR_BADARGUMENT 
  2555. OBJ_ERR_BADHANDLE 
  2556. OBJ_ERR_NOMEMORY 
  2557. OBJ_ERR_NOTROOT 
  2558. OBJ_ERR_OBJECTCORRUPTED 
  2559.  
  2560. Notes 
  2561.  
  2562. Use CmnObjDestroyObject to destroy an object previously created with 
  2563. CmnObjCreateObject.  Any data (see CmnObjSetObjectData) is disposed of and the 
  2564. memory is returned to the system.  It is an error if the root object is 
  2565. specified in phcoObject. 
  2566.  
  2567. For objects with children, the children become adopted children of the object's 
  2568. parent. 
  2569.  
  2570. Related information 
  2571.  
  2572. o HCOOBJECT data type 
  2573. o CmnObjCreateObject 
  2574.  
  2575.  
  2576. ΓòÉΓòÉΓòÉ 10.3. CmnObjInitialize ΓòÉΓòÉΓòÉ
  2577.  
  2578. CmnObjInitialize 
  2579.  
  2580. Purpose 
  2581.  
  2582. This function initializes an instance of the object manager and creates the 
  2583. root object. 
  2584.  
  2585. Syntax 
  2586.  
  2587. (OBJERROR)CmnObjInitialize(pcoriInfo,phcoRoot)
  2588.  
  2589. Parameters 
  2590.  
  2591. pcoriInfo (PCOROOTINFO) - points to a COROOTINFO structure containing desired 
  2592. characteristics of the root object.  If NULL, the default values are used. 
  2593.  
  2594. phcoRoot (PHCOOBJECT) - points to the variable to receive the handle of the 
  2595. root object. 
  2596.  
  2597. Returns 
  2598.  
  2599. This function returns one of the following values: 
  2600.  
  2601. OBJ_ERR_NOERROR 
  2602. OBJ_ERR_BADNAME 
  2603. OBJ_ERR_INITFAILED 
  2604. OBJ_ERR_NOMEMORY 
  2605.  
  2606. Notes 
  2607.  
  2608. Use CmnObjInitialize to create a root object handle which can be used in 
  2609. subsequent calls to other object functions.  The achServer field of the 
  2610. COROOTINFO structure is unused at this time and could possibly disappear in the 
  2611. future. 
  2612.  
  2613. Related information 
  2614.  
  2615. o HCOOBJECT data type 
  2616. o CmnObjTerminate 
  2617.  
  2618.  
  2619. ΓòÉΓòÉΓòÉ 10.4. CmnObjObjectFromName ΓòÉΓòÉΓòÉ
  2620.  
  2621. CmnObjObjectFromName 
  2622.  
  2623. Purpose 
  2624.  
  2625. This function finds an object with a given name. 
  2626.  
  2627. Syntax 
  2628.  
  2629. (OBJERROR)CmnObjObjectFromName(hcoObject,pchName,phcoResult)
  2630.  
  2631. Parameters 
  2632.  
  2633. hcoObject (HCOOBJECT) - handle of the object to search from. 
  2634.  
  2635. pchName (PCHAR) - points to the name of the object to search for. 
  2636.  
  2637. phcoResult (PHCOOBJECT) - points to the variable which receives the handle of 
  2638. the object if found. 
  2639.  
  2640. Returns 
  2641.  
  2642. This function returns one of the following values: 
  2643.  
  2644. OBJ_ERR_NOERROR 
  2645. OBJ_ERR_BADHANDLE 
  2646. OBJ_ERR_NOTFOUND 
  2647.  
  2648. Notes 
  2649.  
  2650. The object name structure is extremely similar to the directory/filename 
  2651. structure of the file system.  Each object has a subname which, when combined 
  2652. with the subnames of its ancestors, produces a fully qualified name; each 
  2653. subname is separated by a backslash. 
  2654.  
  2655. pchName can specify either a name relative to the specified object, or it can 
  2656. specify an absolute name by prepending it with a backslash. Also, as with the 
  2657. file system, you can specify "." and ".." to indicate the current object and 
  2658. its parent, respectively. 
  2659.  
  2660. For example, if you have the following objects with the given relationships 
  2661.  
  2662.                         root
  2663.                         /  \
  2664.                  child1      child2
  2665.                  /  |          |  \
  2666.             child3 child4  child5 child6
  2667.  
  2668. the following calls return the indicated results: 
  2669.  
  2670. CmnObjObjectFromName(root,"child1\\child4") returns child4. 
  2671.  
  2672. CmnObjObjectFromName(child3,"..\\..\\child2\\child5") returns child5. 
  2673.  
  2674. CmnObjObjectFromName(child4,"..\\child3\\..\\child4\\..\\..") returns root. 
  2675.  
  2676. CmnObjObjectFromName(root,"..") returns an error. 
  2677.  
  2678. Related information 
  2679.  
  2680. o HCOOBJECT data type 
  2681. o CmnObjQueryObject 
  2682.  
  2683.  
  2684. ΓòÉΓòÉΓòÉ 10.5. CmnObjQueryObject ΓòÉΓòÉΓòÉ
  2685.  
  2686. CmnObjQueryObject 
  2687.  
  2688. Purpose 
  2689.  
  2690. This function returns an object related to the specified object in the 
  2691. specified way. 
  2692.  
  2693. Syntax 
  2694.  
  2695. (OBJERROR)CmnObjQueryObject(hcoObject,sQuery,phcoResult)
  2696.  
  2697. Parameters 
  2698.  
  2699. hcoObject (HCOOBJECT) - handle of the object to query. 
  2700.  
  2701. sQuery (SHORT) - specifies an OQO constant. 
  2702.  
  2703. phcoResult (PHCOOBJECT) - points to the variable which receives the related 
  2704. object handle. 
  2705.  
  2706. Returns 
  2707.  
  2708. This function returns one of the following values: 
  2709.  
  2710. OBJ_ERR_NOERROR 
  2711. OBJ_ERR_BADARGUMENT 
  2712. OBJ_ERR_BADHANDLE 
  2713. OBJ_ERR_NOTROOT 
  2714.  
  2715. Notes 
  2716.  
  2717. When used with the usNumChildren field of the COOBJECTINFO structure returned 
  2718. by CmnQueryHandleInfo, the OQO_FIRSTCHILD and OQO_NEXT constants can be used to 
  2719. traverse the entire object tree. 
  2720.  
  2721. Note that calling this function with OQO_ROOT is faster that calling 
  2722. CmnObjObjectFromName with "\\", because the latter calls this function. 
  2723.  
  2724. Related information 
  2725.  
  2726. o HCOOBJECT data type 
  2727. o CmnObjObjectFromName 
  2728. o CmnObjQueryObjectData 
  2729. o CmnQueryHandleInfo 
  2730.  
  2731.  
  2732. ΓòÉΓòÉΓòÉ 10.6. CmnObjQueryObjectData ΓòÉΓòÉΓòÉ
  2733.  
  2734. CmnObjQueryObjectData 
  2735.  
  2736. Purpose 
  2737.  
  2738. This function returns the object-specific data. 
  2739.  
  2740. Syntax 
  2741.  
  2742. (OBJERROR)CmnObjQueryObjectData(hcoObject,pvBuffer,pulSzBuf)
  2743.  
  2744. Parameters 
  2745.  
  2746. hcoObject (HCOOBJECT) - handle of the object to query. 
  2747.  
  2748. pvBuffer (PVOID) - points to the buffer to receive the data. If NULL, this 
  2749. function will return the number of bytes needed in pulSzBuf. 
  2750.  
  2751. pulSzBuf (PULONG) - points to the variable containing the size of the buffer 
  2752. pointed to by pvBuffer.  On exit, this variable contains the number of bytes 
  2753. written. 
  2754.  
  2755. Returns 
  2756.  
  2757. This function returns one of the following values: 
  2758.  
  2759. OBJ_ERR_NOERROR 
  2760. OBJ_ERR_BADHANDLE 
  2761.  
  2762. Notes 
  2763.  
  2764. This function should not be confused with CmnQueryHandleInfo, which returns 
  2765. information about the object's current attributes, which does include the 
  2766. object data.  Instead, this function returns only the data that was previously 
  2767. set with the CmnObjSetObjectData function. 
  2768.  
  2769. Related information 
  2770.  
  2771. o HCOOBJECT data type 
  2772. o CmnQueryHandleInfo 
  2773. o CmnObjSetObjectData 
  2774.  
  2775.  
  2776. ΓòÉΓòÉΓòÉ 10.7. CmnObjReset ΓòÉΓòÉΓòÉ
  2777.  
  2778. CmnObjReset 
  2779.  
  2780. Purpose 
  2781.  
  2782. This function deletes all children of the specified root object. 
  2783.  
  2784. Syntax 
  2785.  
  2786. (OBJERROR)CmnObjReset(hcoRoot)
  2787.  
  2788. Parameters 
  2789.  
  2790. hcoRoot (HCOOBJECT) - handle of the root object. 
  2791.  
  2792. Returns 
  2793.  
  2794. This function returns one of the following values: 
  2795.  
  2796. OBJ_ERR_NOERROR 
  2797. OBJ_ERR_BADARGUMENT 
  2798. OBJ_ERR_BADHANDLE 
  2799. OBJ_ERR_BADROOTHANDLE 
  2800. OBJ_ERR_NOTROOT 
  2801.  
  2802. Notes 
  2803.  
  2804. Use CmnObjReset to delete all children objects and their object-data and return 
  2805. the memory to the system. 
  2806.  
  2807. Related information 
  2808.  
  2809. o HCOOBJECT data type 
  2810. o CmnObjTerminate 
  2811.  
  2812.  
  2813. ΓòÉΓòÉΓòÉ 10.8. CmnObjSetObjectData ΓòÉΓòÉΓòÉ
  2814.  
  2815. CmnObjSetObjectData 
  2816.  
  2817. Purpose 
  2818.  
  2819. This function sets the object-specific data. 
  2820.  
  2821. Syntax 
  2822.  
  2823. (OBJERROR)CmnObjSetObjectData(hcoObject,pvBuffer,ulSzBuf)
  2824.  
  2825. Parameters 
  2826.  
  2827. hcoObject (HCOOBJECT) - handle of the object. 
  2828.  
  2829. pvBuffer (PVOID) - points to the buffer from which the data is copied. 
  2830.  
  2831. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuffer. 
  2832.  
  2833. Returns 
  2834.  
  2835. This function returns one of the following values: 
  2836.  
  2837. OBJ_ERR_NOERROR 
  2838. OBJ_ERR_BADARGUMENT 
  2839. OBJ_ERR_BADHANDLE 
  2840. OBJ_ERR_NOMEMORY 
  2841. OBJ_ERR_NOTROOT 
  2842. OBJ_ERR_SIZETOOLARGE 
  2843.  
  2844. Notes 
  2845.  
  2846. Use CmnObjSetObjectData to set any object-specific data which can then be later 
  2847. queried using CmnObjQueryObjectData or by examining the pvData field of the 
  2848. COOBJECTINFO structure returned from CmnQueryHandleInfo. 
  2849.  
  2850. Related information 
  2851.  
  2852. o HCOOBJECT data type 
  2853. o CmnObjQueryObjectData 
  2854. o CmnQueryHandleInfo 
  2855.  
  2856.  
  2857. ΓòÉΓòÉΓòÉ 10.9. CmnObjTerminate ΓòÉΓòÉΓòÉ
  2858.  
  2859. CmnObjTerminate 
  2860.  
  2861. Purpose 
  2862.  
  2863. This function destroys the object manager instance. 
  2864.  
  2865. Syntax 
  2866.  
  2867. (OBJERROR)CmnObjTerminate(phcoRoot)
  2868.  
  2869. Parameters 
  2870.  
  2871. phcoRoot (PHCOOBJECT) - handle of the root object. 
  2872.  
  2873. Returns 
  2874.  
  2875. This function returns one of the following values: 
  2876.  
  2877. OBJ_ERR_NOERROR 
  2878. OBJ_ERR_BADARGUMENT 
  2879. OBJ_ERR_BADHANDLE 
  2880. OBJ_ERR_BADROOTHANDLE 
  2881. OBJ_ERR_NOTROOT 
  2882.  
  2883. Notes 
  2884.  
  2885. Use CmnObjTerminate to destroy the root's children (via CmnObjReset) and to 
  2886. destroy the root object. 
  2887.  
  2888. Related information 
  2889.  
  2890. o HCOOBJECT data type 
  2891. o CmnObjInitialize 
  2892. o CmnObjReset 
  2893.  
  2894.  
  2895. ΓòÉΓòÉΓòÉ 11. Set routines ΓòÉΓòÉΓòÉ
  2896.  
  2897. The purpose of this group is to provide a complete set implementation. Unlike 
  2898. some programming languages, the sets are not limited to 256 elements but 
  2899. instead have a limit of approximately 520000 elements per set (for the 32-bit 
  2900. version of the library, this could conceivably be raised significantly, since 
  2901. the limit mentioned is due to the segmented architecture of 16-bit programs. 
  2902. If you are developing a 32-bit application and have a need for a higher limit, 
  2903. please let me know). Due to the fact that the sets are (currently) implemented 
  2904. as bit-maps, you should also find the performance to be very good. 
  2905.  
  2906. Listed below are the functions which comprise this group: 
  2907.  
  2908. o CmnSetClearElement 
  2909. o CmnSetClearSet 
  2910. o CmnSetCombineSets 
  2911. o CmnSetCreateSet 
  2912. o CmnSetDestroySet 
  2913. o CmnSetFindElement 
  2914. o CmnSetIntersectSets 
  2915. o CmnSetInvertElement 
  2916. o CmnSetInvertSet 
  2917. o CmnSetQueryElement 
  2918. o CmnSetQueryEqualSets 
  2919. o CmnSetSetElement 
  2920. o CmnSetSetSet 
  2921.  
  2922.  
  2923. ΓòÉΓòÉΓòÉ 11.1. CmnSetClearElement ΓòÉΓòÉΓòÉ
  2924.  
  2925. CmnSetClearElement 
  2926.  
  2927. Purpose 
  2928.  
  2929. This function clears an element in a set. 
  2930.  
  2931. Syntax 
  2932.  
  2933. (BOOL)CmnSetClearElement(hcsSet,ulElement);
  2934.  
  2935. Parameters 
  2936.  
  2937. hcsSet (HCSSET) - handle of the set. 
  2938.  
  2939. ulElement (ULONG) - specifies the 0-based element to clear. 
  2940.  
  2941. Returns 
  2942.  
  2943. This function returns TRUE if successful, or FALSE otherwise. 
  2944.  
  2945. Notes 
  2946.  
  2947. Use CmnSetClearElement to clear an element from a set.  To clear all of the 
  2948. elements in a set, use CmnSetClearSet. 
  2949.  
  2950. Related information 
  2951.  
  2952. o HCSSET data type 
  2953. o CmnSetClearSet 
  2954.  
  2955.  
  2956. ΓòÉΓòÉΓòÉ 11.2. CmnSetClearSet ΓòÉΓòÉΓòÉ
  2957.  
  2958. CmnSetClearSet 
  2959.  
  2960. Purpose 
  2961.  
  2962. This function clears all of the elements in a set. 
  2963.  
  2964. Syntax 
  2965.  
  2966. (BOOL)CmnSetClearSet(hcsSet);
  2967.  
  2968. Parameters 
  2969.  
  2970. hcsSet (HCSSET) - handle of the set to clear. 
  2971.  
  2972. Returns 
  2973.  
  2974. This function returns TRUE if successful, or FALSE otherwise. 
  2975.  
  2976. Notes 
  2977.  
  2978. Use CmnSetClearSet to clear all of the elements in a set. To clear a single 
  2979. element, use CmnSetClearElement. 
  2980.  
  2981. This call is fast in terms of execution time. 
  2982.  
  2983. Related information 
  2984.  
  2985. o HCSSET data type 
  2986. o CmnSetClearElement 
  2987.  
  2988.  
  2989. ΓòÉΓòÉΓòÉ 11.3. CmnSetCombineSets ΓòÉΓòÉΓòÉ
  2990.  
  2991. CmnSetCombineSets 
  2992.  
  2993. Purpose 
  2994.  
  2995. This function creates a new set containing all of the elements set from two 
  2996. sets. 
  2997.  
  2998. Syntax 
  2999.  
  3000. (HCSSET)CmnSetCombineSets(hcsSet1,hcsSet2);
  3001.  
  3002. Parameters 
  3003.  
  3004. hcsSet1 (HCSSET) - handle of a set to combine. 
  3005.  
  3006. hcsSet2 (HCSSET) - handle of a set to combine. 
  3007.  
  3008. Returns 
  3009.  
  3010. This function returns a handle to the resulting set if successful, or NULL 
  3011. otherwise. 
  3012.  
  3013. Notes 
  3014.  
  3015. Use CmnSetCombineSets to perform a union of two sets.  Note that the two sets 
  3016. do not have to be of equal size. 
  3017.  
  3018. To perform an intersection of two sets, use CmnSetIntersectSets. 
  3019.  
  3020. Related information 
  3021.  
  3022. o HCSSET data type 
  3023. o CmnSetIntersectSets 
  3024.  
  3025.  
  3026. ΓòÉΓòÉΓòÉ 11.4. CmnSetCreateSet ΓòÉΓòÉΓòÉ
  3027.  
  3028. CmnSetCreateSet 
  3029.  
  3030. Purpose 
  3031.  
  3032. This function creates a new set handle for use in subsequent calls to the 
  3033. CmnSet functions. 
  3034.  
  3035. Syntax 
  3036.  
  3037. (BOOL)CmnSetCreateSet(ulMaxElems,phcsSet);
  3038.  
  3039. Parameters 
  3040.  
  3041. ulMaxElems (ULONG) - specifies the maximum number of elements the set is to 
  3042. hold. 
  3043.  
  3044. phcsSet (PHCSSET) - points to the variable to receive the created set handle. 
  3045.  
  3046. Returns 
  3047.  
  3048. This function returns TRUE if successful, or FALSE otherwise. 
  3049.  
  3050. Notes 
  3051.  
  3052. Use CmnSetCreateSet to create a new set for use in subsequent calls to the 
  3053. CmnSet functions.  Note that there is currently an upper limit of 522240 for 
  3054. ulMaxElems. 
  3055.  
  3056. Related information 
  3057.  
  3058. o HCSSET data type 
  3059. o CmnSetDestroySet 
  3060.  
  3061.  
  3062. ΓòÉΓòÉΓòÉ 11.5. CmnSetDestroySet ΓòÉΓòÉΓòÉ
  3063.  
  3064. CmnSetDestroySet 
  3065.  
  3066. Purpose 
  3067.  
  3068. This function destroys a set handle. 
  3069.  
  3070. Syntax 
  3071.  
  3072. (BOOL)CmnSetDestroySet(phcsSet);
  3073.  
  3074. Parameters 
  3075.  
  3076. phcsSet (PHCSSET) - points to the variable containing the handle of the set to 
  3077. destroy.  On return, the variable contains NULL. 
  3078.  
  3079. Returns 
  3080.  
  3081. This function returns TRUE if successful, or FALSE otherwise. 
  3082.  
  3083. Notes 
  3084.  
  3085. Use CmnSetDestroySet to destroy a handle to a set and return any memory to the 
  3086. system. 
  3087.  
  3088. Related information 
  3089.  
  3090. o HCSSET data type 
  3091. o CmnSetCreateSet 
  3092.  
  3093.  
  3094. ΓòÉΓòÉΓòÉ 11.6. CmnSetFindElement ΓòÉΓòÉΓòÉ
  3095.  
  3096. CmnSetFindElement 
  3097.  
  3098. Purpose 
  3099.  
  3100. This function finds the nth element in a set that is either set or clear. 
  3101.  
  3102. Syntax 
  3103.  
  3104. (LONG)CmnSetFindElement(hcsSet,ulNumber,usType)
  3105.  
  3106. Parameters 
  3107.  
  3108. hcsSet (HCSSET) - handle of the set. 
  3109.  
  3110. ulNumber (ULONG) - specifies the nth element to find. 
  3111.  
  3112. usType (USHORT) - specifies a SFE_ constant. 
  3113.  
  3114. Returns 
  3115.  
  3116. This function returns the index of the element found, SFE_NOTFOUND if the nth 
  3117. element was not found, or SFE_ERROR if an error occurred. 
  3118.  
  3119. Notes 
  3120.  
  3121. Use CmnSetFindElement to find the nth element set or clear in a set (i.e. the 
  3122. 3rd clear element). 
  3123.  
  3124. Related information 
  3125.  
  3126. o HCSSET data type 
  3127. o CmnSetClearElement 
  3128. o CmnSetSetElement 
  3129.  
  3130.  
  3131. ΓòÉΓòÉΓòÉ 11.7. CmnSetIntersectSets ΓòÉΓòÉΓòÉ
  3132.  
  3133. CmnSetIntersectSets 
  3134.  
  3135. Purpose 
  3136.  
  3137. This function creates a new set containing elements that were set in both of 
  3138. the specified sets. 
  3139.  
  3140. Syntax 
  3141.  
  3142. (HCSSET)CmnSetIntersectSets(hcsSet1,hcsSet2);
  3143.  
  3144. Parameters 
  3145.  
  3146. hcsSet1 (HCSSET) - handle of a set to intersect. 
  3147.  
  3148. hcsSet2 (HCSSET) - handle of a set to intersect. 
  3149.  
  3150. Returns 
  3151.  
  3152. This function returns a handle to the resulting set if successful, or NULL 
  3153. otherwise. 
  3154.  
  3155. Notes 
  3156.  
  3157. Use CmnSetIntersectSets to perform an intersection of two sets. Note that the 
  3158. two sets do not have to be of equal size. 
  3159.  
  3160. Related information 
  3161.  
  3162. o HCSSET data type 
  3163. o CmnSetCombineSets 
  3164.  
  3165.  
  3166. ΓòÉΓòÉΓòÉ 11.8. CmnSetInvertElement ΓòÉΓòÉΓòÉ
  3167.  
  3168. CmnSetInvertElement 
  3169.  
  3170. Purpose 
  3171.  
  3172. This function inverts the state of an element in a set. 
  3173.  
  3174. Syntax 
  3175.  
  3176. (BOOL)CmnSetInvertElement(hcsSet,ulElement);
  3177.  
  3178. Parameters 
  3179.  
  3180. hcsSet (HCSSET) - handle of the set. 
  3181.  
  3182. ulElement (ULONG) - specifies the 0-based element to invert. 
  3183.  
  3184. Returns 
  3185.  
  3186. This function returns TRUE if successful, or FALSE otherwise. 
  3187.  
  3188. Notes 
  3189.  
  3190. Use CmnSetInvertElement to invert an element in a set.  That is, if it was set, 
  3191. it is cleared (and vice versa).  To invert an entire set, use CmnSetInvertSet. 
  3192.  
  3193. Related information 
  3194.  
  3195. o HCSSET data type 
  3196. o CmnSetInvertSet 
  3197.  
  3198.  
  3199. ΓòÉΓòÉΓòÉ 11.9. CmnSetInvertSet ΓòÉΓòÉΓòÉ
  3200.  
  3201. CmnSetInvertSet 
  3202.  
  3203. Purpose 
  3204.  
  3205. This function inverts the state of all of the elements in a set. 
  3206.  
  3207. Syntax 
  3208.  
  3209. (BOOL)CmnSetInvertSet(hcsSet);
  3210.  
  3211. Parameters 
  3212.  
  3213. hcsSet (HCSSET) - handle of the set to invert. 
  3214.  
  3215. Returns 
  3216.  
  3217. This function returns TRUE if successful, or FALSE otherwise. 
  3218.  
  3219. Notes 
  3220.  
  3221. Use CmnSetInvertSet to invert all of the elements of a set.  To invert a single 
  3222. element, use CmnSetInvertElement. 
  3223.  
  3224. This call is fast in terms of execution time. 
  3225.  
  3226. Related information 
  3227.  
  3228. o HCSSET data type 
  3229. o CmnSetInvertElement 
  3230.  
  3231.  
  3232. ΓòÉΓòÉΓòÉ 11.10. CmnSetQueryElement ΓòÉΓòÉΓòÉ
  3233.  
  3234. CmnSetQueryElement 
  3235.  
  3236. Purpose 
  3237.  
  3238. This function queries the state of an element in a set. 
  3239.  
  3240. Syntax 
  3241.  
  3242. (SHORT)CmnSetQueryElement(hcsSet,ulElement);
  3243.  
  3244. Parameters 
  3245.  
  3246. hcsSet (HCSSET) - handle of the set to query. 
  3247.  
  3248. ulElement (ULONG) - specifies the 0-based element to query. 
  3249.  
  3250. Returns 
  3251.  
  3252. This function returns SQE_SET if the element is set, SQE_CLEAR if the element 
  3253. is cleared, or SQE_ERROR if an error occurred. 
  3254.  
  3255. Notes 
  3256.  
  3257. Use CmnSetQueryElement to query the state of an element. 
  3258.  
  3259. Related information 
  3260.  
  3261. o HCSSET data type 
  3262.  
  3263.  
  3264. ΓòÉΓòÉΓòÉ 11.11. CmnSetQueryEqualSets ΓòÉΓòÉΓòÉ
  3265.  
  3266. CmnSetQueryEqualSets 
  3267.  
  3268. Purpose 
  3269.  
  3270. This function determines whether or not two sets are equal. 
  3271.  
  3272. Syntax 
  3273.  
  3274. (SHORT)CmnSetQueryEqualSets(hcsSet1,hcsSet2);
  3275.  
  3276. Parameters 
  3277.  
  3278. hcsSet1 (HCSSET) - handle of a set to compare. 
  3279.  
  3280. hcsSet2 (HCSSET) - handle of a set to compare. 
  3281.  
  3282. Returns 
  3283.  
  3284. This function returns SQES_EQUAL if the sets have the same number of elements 
  3285. and the same elements are set in both sets, SQES_NOTEQUAL if the sets do not 
  3286. have the same number of elements or the same elements are not set in both sets, 
  3287. or SQES_ERROR if an error occurred. 
  3288.  
  3289. Notes 
  3290.  
  3291. Use CmnSetQueryEqualSets to determine whether or not two sets are equal. 
  3292.  
  3293. This call is fast in terms of execution time. 
  3294.  
  3295. Related information 
  3296.  
  3297. o HCSSET data type 
  3298.  
  3299.  
  3300. ΓòÉΓòÉΓòÉ 11.12. CmnSetSetElement ΓòÉΓòÉΓòÉ
  3301.  
  3302. CmnSetSetElement 
  3303.  
  3304. Purpose 
  3305.  
  3306. This function sets an element in a set. 
  3307.  
  3308. Syntax 
  3309.  
  3310. (BOOL)CmnSetSetElement(hcsSet,ulElement);
  3311.  
  3312. Parameters 
  3313.  
  3314. hcsSet (HCSSET) - handle of the set. 
  3315.  
  3316. ulElement (ULONG) - specifies the 0-based element to set. 
  3317.  
  3318. Returns 
  3319.  
  3320. This function returns TRUE if successful, or FALSE otherwise. 
  3321.  
  3322. Notes 
  3323.  
  3324. Use CmnSetSetElement to set an element in a set.  To set all of the elements in 
  3325. a set, use CmnSetSetSet. 
  3326.  
  3327. Related information 
  3328.  
  3329. o HCSSET data type 
  3330. o CmnSetSetSet 
  3331.  
  3332.  
  3333. ΓòÉΓòÉΓòÉ 11.13. CmnSetSetSet ΓòÉΓòÉΓòÉ
  3334.  
  3335. CmnSetSetSet 
  3336.  
  3337. Purpose 
  3338.  
  3339. This function sets all of the elements in a set. 
  3340.  
  3341. Syntax 
  3342.  
  3343. (BOOL)CmnSetSetSet(hcsSet);
  3344.  
  3345. Parameters 
  3346.  
  3347. hcsSet (HCSSET) - handle of the set to set. 
  3348.  
  3349. Returns 
  3350.  
  3351. This function returns TRUE if successful, or FALSE otherwise. 
  3352.  
  3353. Notes 
  3354.  
  3355. Use CmnSetSetSet to set all of the elements in a set. To set a single element, 
  3356. use CmnSetSetElement. 
  3357.  
  3358. This call is fast in terms of execution time. 
  3359.  
  3360. Related information 
  3361.  
  3362. o HCSSET data type 
  3363. o CmnSetSetElement 
  3364.  
  3365.  
  3366. ΓòÉΓòÉΓòÉ 12. Signal routines ΓòÉΓòÉΓòÉ
  3367.  
  3368. The purpose of this group is to provide an easy method of communication between 
  3369. different threads in an application.  Signals can either be via 32-bit values 
  3370. or individual bits in a 32-bit word, and can be waited on like you can with 
  3371. semaphores.  Unfortunately, since this functions are not system-wide objects, 
  3372. they cannot be used for interprocess communication. 
  3373.  
  3374. Listed below are the functions which comprise this group: 
  3375.  
  3376. o CmnSigClearAllSignalBits 
  3377. o CmnSigClearSignalBit 
  3378. o CmnSigCreateSignal 
  3379. o CmnSigCreateSignalList 
  3380. o CmnSigDestroySignal 
  3381. o CmnSigDestroySignalList 
  3382. o CmnSigQuerySignal 
  3383. o CmnSigQuerySignalId 
  3384. o CmnSigQuerySignalValue 
  3385. o CmnSigSetAllSignalBits 
  3386. o CmnSigSetAllSignalValues 
  3387. o CmnSigSetSignalBit 
  3388. o CmnSigSetSignalValue 
  3389. o CmnSigWaitAllSignalBits 
  3390. o CmnSigWaitAllSignalValues 
  3391. o CmnSigWaitSignalBit 
  3392. o CmnSigWaitSignalValue 
  3393.  
  3394.  
  3395. ΓòÉΓòÉΓòÉ 12.1. CmnSigClearAllSignalBits ΓòÉΓòÉΓòÉ
  3396.  
  3397. CmnSigClearAllSignalBits 
  3398.  
  3399. Purpose 
  3400.  
  3401. This function clears all of the specified bits in all of the signal handles in 
  3402. a signal list. 
  3403.  
  3404. Syntax 
  3405.  
  3406. (BOOL)CmnSigClearAllSignalBits(hcsList,ulSignal);
  3407.  
  3408. Parameters
  3409.  
  3410. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3411.  
  3412. ulSignal (ULONG) - specifies one or more bits to clear. 
  3413.  
  3414. Returns 
  3415.  
  3416. This function returns TRUE if successful, or FALSE otherwise. 
  3417.  
  3418. Notes 
  3419.  
  3420. Use CmnSigClearAllSignalBits to clear all of the specified bits in all of the 
  3421. signal handles in a signal list.  To clear specified bits from a single signal 
  3422. handle, use CmnSigClearSignalBit. 
  3423.  
  3424. Related information 
  3425.  
  3426. o HCSSIGNALLIST data type 
  3427. o CmnSigClearSignalBit 
  3428. o CmnSigSetAllSignalBits 
  3429.  
  3430.  
  3431. ΓòÉΓòÉΓòÉ 12.2. CmnSigClearSignalBit ΓòÉΓòÉΓòÉ
  3432.  
  3433. CmnSigClearSignalBit 
  3434.  
  3435. Purpose 
  3436.  
  3437. This function clears one or more bits in a signal. 
  3438.  
  3439. Syntax 
  3440.  
  3441. (BOOL)CmnSigClearSignalBit(hcSignal,ulSignal);
  3442.  
  3443. Parameters 
  3444.  
  3445. hcSignal (HCSSIGNAL) - handle to the signal. 
  3446.  
  3447. ulSignal (ULONG) - specifies one or more bits to clear. 
  3448.  
  3449. Returns 
  3450.  
  3451. This function returns TRUE if successful, or FALSE otherwise. 
  3452.  
  3453. Notes 
  3454.  
  3455. Use CmnSigClearSignalBit to clear one or more bits from a signal. 
  3456.  
  3457. Related information 
  3458.  
  3459. o HCSSIGNAL data type 
  3460. o CmnSigSetSignalBit 
  3461.  
  3462.  
  3463. ΓòÉΓòÉΓòÉ 12.3. CmnSigCreateSignal ΓòÉΓòÉΓòÉ
  3464.  
  3465. CmnSigCreateSignal 
  3466.  
  3467. Purpose 
  3468.  
  3469. This function creates a signal handle within a signal list. 
  3470.  
  3471. Syntax 
  3472.  
  3473. (BOOL)CmnSigCreateSignal(hcsList,ulId,phcSignal);
  3474.  
  3475. Parameters 
  3476.  
  3477. hcsList (HCSSIGNALLIST) - handle to the signal list to which the signal handle 
  3478. will belong. 
  3479.  
  3480. ulId (ULONG) - specified the identifer of the signal handle. This must be 
  3481. unique. 
  3482.  
  3483. phcSignal (PHCSSIGNAL) - points to the variable to receive the created signal 
  3484. handle. 
  3485.  
  3486. Returns 
  3487.  
  3488. This function returns TRUE if successful, or FALSE otherwise. 
  3489.  
  3490. Notes 
  3491.  
  3492. Use CmnSigCreateSignal to create a signal handle for use in subsequent calls to 
  3493. the CmnSig routines.  ulId must be a unique identifier within the signal list. 
  3494.  
  3495. Note that because this function requires the handle to a signal list, 
  3496. CmnSigCreateSignalList must be called prior to using this function. 
  3497.  
  3498. Related information 
  3499.  
  3500. o HCSSIGNALLIST data type 
  3501. o HCSSIGNAL data type 
  3502. o CmnSigCreateSignalList 
  3503. o CmnSigDestroySignal 
  3504.  
  3505.  
  3506. ΓòÉΓòÉΓòÉ 12.4. CmnSigCreateSignalList ΓòÉΓòÉΓòÉ
  3507.  
  3508. CmnSigCreateSignalList 
  3509.  
  3510. Purpose 
  3511.  
  3512. This function creates a signal list handle from which signal handles can be 
  3513. created. 
  3514.  
  3515. Syntax 
  3516.  
  3517. (BOOL)CmnSigCreateSignalList(phcsList);
  3518.  
  3519. Parameters 
  3520.  
  3521. phcsList (PHCSSIGNALLIST) - points to the variable that receives the created 
  3522. signal list handle. 
  3523.  
  3524. Returns 
  3525.  
  3526. This function returns TRUE if successful, or FALSE otherwise. 
  3527.  
  3528. Notes 
  3529.  
  3530. Use CmnSigCreateSignalList to create a signal list handle. After this is 
  3531. created, CmnSigCreateSignal can be called to create signal handles to be used 
  3532. in other CmnSig functions. 
  3533.  
  3534. Related information 
  3535.  
  3536. o HCSSIGNALLIST data type 
  3537. o CmnSigCreateSignal 
  3538. o CmnSigDestroySignalList 
  3539.  
  3540.  
  3541. ΓòÉΓòÉΓòÉ 12.5. CmnSigDestroySignal ΓòÉΓòÉΓòÉ
  3542.  
  3543. CmnSigDestroySignal 
  3544.  
  3545. Purpose 
  3546.  
  3547. This function destroys a signal handle. 
  3548.  
  3549. Syntax 
  3550.  
  3551. (BOOL)CmnSigDestroySignal(phcSignal);
  3552.  
  3553. Parameters 
  3554.  
  3555. phcSignal (PHCSSIGNAL) - points to the variable which specifies the handle of 
  3556. the signal to destroy.  On return, this variable contains NULL. 
  3557.  
  3558. Returns 
  3559.  
  3560. This function returns TRUE if successful, or FALSE otherwise. 
  3561.  
  3562. Notes 
  3563.  
  3564. Use CmnSigDestroySignal to destroy a signal handle.  This call is not required 
  3565. prior to calling CmnSigDestroySignalList because it will destroy all signal 
  3566. handles belong to the signal list. 
  3567.  
  3568. Related information 
  3569.  
  3570. o HCSSIGNAL data type 
  3571. o CmnSigCreateSignal 
  3572.  
  3573.  
  3574. ΓòÉΓòÉΓòÉ 12.6. CmnSigDestroySignalList ΓòÉΓòÉΓòÉ
  3575.  
  3576. CmnSigDestroySignalList 
  3577.  
  3578. Purpose 
  3579.  
  3580. This function destroys a signal list. 
  3581.  
  3582. Syntax 
  3583.  
  3584. (BOOL)CmnSigDestroySignalList(phcsList);
  3585.  
  3586. Parameters 
  3587.  
  3588. phcsList (PHCSSIGNALLIST) - points to the variable which specifies the handle 
  3589. of the signal list to destroy.  On return, this variable contains NULL. 
  3590.  
  3591. Returns 
  3592.  
  3593. This function returns TRUE if successful, or FALSE otherwise. 
  3594.  
  3595. Notes 
  3596.  
  3597. Use CmnSigDestroySignalList to destroy a signal list and all associated signal 
  3598. handles. 
  3599.  
  3600. Related information 
  3601.  
  3602. o HCSSIGNALLIST data type 
  3603. o CmnSigCreateSignalList 
  3604.  
  3605.  
  3606. ΓòÉΓòÉΓòÉ 12.7. CmnSigQuerySignal ΓòÉΓòÉΓòÉ
  3607.  
  3608. CmnSigQuerySignal 
  3609.  
  3610. Purpose 
  3611.  
  3612. This function queries a signal list for a signal handle with a specific 
  3613. identifier. 
  3614.  
  3615. Syntax 
  3616.  
  3617. (BOOL)CmnSigQuerySignal(hcsList,ulId,phcSignal);
  3618.  
  3619. Parameters 
  3620.  
  3621. hcsList (HCSSIGNALLIST) - handle to the signal list to query. 
  3622.  
  3623. ulId (ULONG) - specifies the identifier of the signal handle desired. 
  3624.  
  3625. phcSignal (PHCSSIGNAL) - points to the variable to receive the result.  On 
  3626. return, the variable contains the signal handle with the specified identifier. 
  3627.  
  3628. Returns 
  3629.  
  3630. This function returns TRUE if successful, or FALSE otherwise. 
  3631.  
  3632. Notes 
  3633.  
  3634. Use CmnSigQuerySignal to query a signal list for the signal handle that was 
  3635. created with the specified identifier. 
  3636.  
  3637. Related information 
  3638.  
  3639. o HCSSIGNAL data type 
  3640. o HCSSIGNALLIST data type 
  3641. o CmnSigCreateSignal 
  3642. o CmnSigQuerySignalId 
  3643.  
  3644.  
  3645. ΓòÉΓòÉΓòÉ 12.8. CmnSigQuerySignalId ΓòÉΓòÉΓòÉ
  3646.  
  3647. CmnSigQuerySignalId 
  3648.  
  3649. Purpose 
  3650.  
  3651. This function returns the identifier of a signal handle. 
  3652.  
  3653. Syntax 
  3654.  
  3655. (BOOL)CmnSigQuerySignalId(hcSignal,pulId);
  3656.  
  3657. Parameters 
  3658.  
  3659. hcSignal (HCSSIGNAL) - handle to the signal. 
  3660.  
  3661. pulId (PULONG) - points to the variable that receives the identifier of the 
  3662. signal handle. 
  3663.  
  3664. Returns 
  3665.  
  3666. This function returns TRUE if successful, or FALSE otherwise. 
  3667.  
  3668. Notes 
  3669.  
  3670. Use CmnSigQuerySignalId to query the identifier of a signal handle.  This 
  3671. identifier is specified when the signal handle is created. 
  3672.  
  3673. Related information 
  3674.  
  3675. o HCSSIGNAL data type 
  3676. o CmnSigCreateSignal 
  3677.  
  3678.  
  3679. ΓòÉΓòÉΓòÉ 12.9. CmnSigQuerySignalValue ΓòÉΓòÉΓòÉ
  3680.  
  3681. CmnSigQuerySignalValue 
  3682.  
  3683. Purpose 
  3684.  
  3685. This function queries the current value of a signal handle. 
  3686.  
  3687. Syntax 
  3688.  
  3689. (BOOL)CmnSigQuerySignalValue(hcSignal,pulSignal);
  3690.  
  3691. Parameters 
  3692.  
  3693. hcSignal (HCSSIGNAL) - handle to the signal. 
  3694.  
  3695. pulSignal (PULONG) - points to the variable that receives the value of the 
  3696. signal handle. 
  3697.  
  3698. Returns 
  3699.  
  3700. This function returns TRUE if successful, or FALSE otherwise. 
  3701.  
  3702. Notes 
  3703.  
  3704. Use CmnSigQuerySignalValue to query the current value of a signal handle. 
  3705.  
  3706. Related information 
  3707.  
  3708. o HCSSIGNAL data type 
  3709. o CmnSigSetSignalValue 
  3710.  
  3711.  
  3712. ΓòÉΓòÉΓòÉ 12.10. CmnSigSetAllSignalBits ΓòÉΓòÉΓòÉ
  3713.  
  3714. CmnSigSetAllSignalBits 
  3715.  
  3716. Purpose 
  3717.  
  3718. This function sets specific bits in all signals in a signal list. 
  3719.  
  3720. Syntax 
  3721.  
  3722. (BOOL)CmnSigSetAllSignalBits(hcsList,ulSignal);
  3723.  
  3724. Parameters
  3725.  
  3726. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3727.  
  3728. ulSignal (ULONG) - specifies one or more bits to set. 
  3729.  
  3730. Returns 
  3731.  
  3732. This function returns TRUE if successful, or FALSE otherwise. 
  3733.  
  3734. Notes 
  3735.  
  3736. Use CmnSigSetAllSignalBits to set a specific set of bits in all signals in a 
  3737. signal list.  This could be used to reset the acknowledgement signal from 
  3738. multiple threads by the initiator of the inter-thread conversation. 
  3739.  
  3740. Related information 
  3741.  
  3742. o HCSSIGNALLIST data type 
  3743. o CmnSigClearAllSignalBits 
  3744. o CmnSigSetAllSignalValues 
  3745.  
  3746.  
  3747. ΓòÉΓòÉΓòÉ 12.11. CmnSigSetAllSignalValues ΓòÉΓòÉΓòÉ
  3748.  
  3749. CmnSigSetAllSignalValues 
  3750.  
  3751. Purpose 
  3752.  
  3753. This function sets all of the signal values in a signal list to a specific 
  3754. value. 
  3755.  
  3756. Syntax 
  3757.  
  3758. (BOOL)CmnSigSetAllSignalValues(hcsList,ulSignal);
  3759.  
  3760. Parameters
  3761.  
  3762. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3763.  
  3764. ulSignal (ULONG) - specifies the new signal value. 
  3765.  
  3766. Returns 
  3767.  
  3768. This function returns TRUE if successful, or FALSE otherwise. 
  3769.  
  3770. Notes 
  3771.  
  3772. Use CmnSigSetAllSignalValues to set all of the signal values in a signal list 
  3773. to a specific value.  This could be used to reset the acknowledgement signal 
  3774. from multiple threads by the initiator of the inter-thread conversation. 
  3775.  
  3776. Related information 
  3777.  
  3778. o HCSSIGNALLIST data type 
  3779. o CmnSigSetAllSignalBits 
  3780.  
  3781.  
  3782. ΓòÉΓòÉΓòÉ 12.12. CmnSigSetSignalValue ΓòÉΓòÉΓòÉ
  3783.  
  3784. CmnSigSetSignalValue 
  3785.  
  3786. Purpose 
  3787.  
  3788. This function sets the current value of a signal handle. 
  3789.  
  3790. Syntax 
  3791.  
  3792. (BOOL)CmnSigSetSignalValue(hcSignal,ulSignal);
  3793.  
  3794. Parameters 
  3795.  
  3796. hcSignal (HCSSIGNAL) - handle to the signal. 
  3797.  
  3798. ulSignal (ULONG) - specifies the new value of the signal. 
  3799.  
  3800. Returns 
  3801.  
  3802. This function returns TRUE if successful, or FALSE otherwise. 
  3803.  
  3804. Notes 
  3805.  
  3806. Use CmnSigSetSignalValue to set the current value of a signal value.  To set or 
  3807. clear individual bits of the signal value, use CmnSigSetSignalBit and 
  3808. CmnSigClearSignalBit. 
  3809.  
  3810. Related information 
  3811.  
  3812. o HCSSIGNAL data type 
  3813. o CmnSigClearSignalBit 
  3814. o CmnSigQuerySignalValue 
  3815. o CmnSigSetSignalBit 
  3816.  
  3817.  
  3818. ΓòÉΓòÉΓòÉ 12.13. CmnSigSetSignalBit ΓòÉΓòÉΓòÉ
  3819.  
  3820. CmnSigSetSignalBit 
  3821.  
  3822. Purpose 
  3823.  
  3824. This function sets one or more bits in a signal. 
  3825.  
  3826. Syntax 
  3827.  
  3828. (BOOL)CmnSigSetSignalBit(hcSignal,ulSignal);
  3829.  
  3830. Parameters 
  3831.  
  3832. hcSignal (HCSSIGNAL) - handle to the signal. 
  3833.  
  3834. ulSignal (ULONG) - specifies one or more bits to set. 
  3835.  
  3836. Returns 
  3837.  
  3838. This function returns TRUE if successful, or FALSE otherwise. 
  3839.  
  3840. Notes 
  3841.  
  3842. Use CmnSigSetSignalBit to set one or more bits in a signal. 
  3843.  
  3844. Related information 
  3845.  
  3846. o HCSSIGNAL data type 
  3847. o CmnSigClearSignalBit 
  3848.  
  3849.  
  3850. ΓòÉΓòÉΓòÉ 12.14. CmnSigWaitAllSignalBits ΓòÉΓòÉΓòÉ
  3851.  
  3852. CmnSigWaitAllSignalBits 
  3853.  
  3854. Purpose 
  3855.  
  3856. This function waits until all of the specified bits are set in all of the 
  3857. signal handles belonging to a signal list. 
  3858.  
  3859. Syntax 
  3860.  
  3861. (USHORT)CmnSigWaitAllSignalBits(hcsList,ulSignal,lTimeout);
  3862.  
  3863. Parameters 
  3864.  
  3865. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3866.  
  3867. ulSignal (ULONG) - specifies the bits to wait for. 
  3868.  
  3869. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  3870. constant. 
  3871.  
  3872. Returns 
  3873.  
  3874. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  3875. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  3876. occurred. 
  3877.  
  3878. Notes 
  3879.  
  3880. Use CmnSigWaitAllSignalBits to wait for all of the specified bits in all of the 
  3881. signal handles in a signal list to be set.  This could be used as part of a 
  3882. handshaking mechanism, where one thread calls CmnSigSetAllSignalBits to 
  3883. indicate to the other threads that some function is to be performed and then 
  3884. follows with a call to this function to wait for each signal to indicate (via 
  3885. CmnSigSetSignalBit) that it has completed the request. 
  3886.  
  3887. Related information 
  3888.  
  3889. o SWS_TIMEOUT_ constants 
  3890. o HCSSIGNALLIST data type 
  3891. o CmnSigClearAllSignalBits 
  3892. o CmnSigSetAllSignalValues 
  3893. o CmnSigWaitAllSignalValues 
  3894.  
  3895.  
  3896. ΓòÉΓòÉΓòÉ 12.15. CmnSigWaitAllSignalValues ΓòÉΓòÉΓòÉ
  3897.  
  3898. CmnSigWaitAllSignalValues 
  3899.  
  3900. Purpose 
  3901.  
  3902. This function waits until all of the signal values in a signal list are equal 
  3903. to a specific value. 
  3904.  
  3905. Syntax 
  3906.  
  3907. (USHORT)CmnSigWaitAllSignalValues(hcsList,ulSignal,lTimeout);
  3908.  
  3909. Parameters 
  3910.  
  3911. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3912.  
  3913. ulSignal (ULONG) - specifies the value to wait for. 
  3914.  
  3915. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  3916. constant. 
  3917.  
  3918. Returns 
  3919.  
  3920. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  3921. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  3922. occurred. 
  3923.  
  3924. Notes 
  3925.  
  3926. Use CmnSigWaitAllSignalValues to wait for all signal values in a signal list to 
  3927. equal a specific value.  This could be used to wait for an acknowledgement from 
  3928. multiple threads after they have finished processing a task. 
  3929.  
  3930. Related information 
  3931.  
  3932. o SWS_TIMEOUT_ constants 
  3933. o HCSSIGNALLIST data type 
  3934. o CmnSigSetAllSignalValues 
  3935. o CmnSigWaitAllSignalBits 
  3936.  
  3937.  
  3938. ΓòÉΓòÉΓòÉ 12.16. CmnSigWaitSignalBit ΓòÉΓòÉΓòÉ
  3939.  
  3940. CmnSigWaitSignalBit 
  3941.  
  3942. Purpose 
  3943.  
  3944. This function waits for a specific set of bits to be set in a signal handle. 
  3945.  
  3946. Syntax 
  3947.  
  3948. (USHORT)CmnSigWaitSignalBit(hcSignal,ulSignal,lTimeout);
  3949.  
  3950. Parameters 
  3951.  
  3952. hcSignal (HCSSIGNAL) - handle to the signal. 
  3953.  
  3954. ulSignal (ULONG) - specifies one or more bits to wait for. 
  3955.  
  3956. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  3957. constant. 
  3958.  
  3959. Returns 
  3960.  
  3961. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  3962. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  3963. occurred. 
  3964.  
  3965. Notes 
  3966.  
  3967. Use CmnSigWaitSignalBit to wait for a specific set of bits in a signal handle 
  3968. to be set.  This could be used by a thread to wait until a bit is set before 
  3969. performing some action. 
  3970.  
  3971. Related information 
  3972.  
  3973. o SWS_TIMEOUT_ constants 
  3974. o HCSSIGNAL data type 
  3975. o CmnSigClearSignalBit 
  3976. o CmnSigSetSignalBit 
  3977.  
  3978.  
  3979. ΓòÉΓòÉΓòÉ 12.17. CmnSigWaitSignalValue ΓòÉΓòÉΓòÉ
  3980.  
  3981. CmnSigWaitSignalValue 
  3982.  
  3983. Purpose 
  3984.  
  3985. This function waits until the value of a signal handle equals a specific value. 
  3986.  
  3987. Syntax 
  3988.  
  3989. (USHORT)CmnSigWaitSignalValue(hcSignal,ulSignal,lTimeout);
  3990.  
  3991. Parameters 
  3992.  
  3993. hcSignal (HCSSIGNAL) - handle to the signal. 
  3994.  
  3995. ulSignal (ULONG) - specifies the value to wait for. 
  3996.  
  3997. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  3998. constant. 
  3999.  
  4000. Returns 
  4001.  
  4002. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  4003. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  4004. occurred. 
  4005.  
  4006. Notes 
  4007.  
  4008. Use CmnSigWaitSignalValue to wait for the value of a signal handle equals a 
  4009. specific value.  This could be used in a handshaking protocol between multiple 
  4010. threads. 
  4011.  
  4012. Related information 
  4013.  
  4014. o SWS_TIMEOUT_ constants 
  4015. o HCSSIGNAL data type 
  4016. o CmnSigSetSignalValue 
  4017.  
  4018.  
  4019. ΓòÉΓòÉΓòÉ 13. Sprite routines ΓòÉΓòÉΓòÉ
  4020.  
  4021. The purpose of this group is to provide the capability to draw bitmaps with 
  4022. transparancy; the difference between a sprite resource and the system-defined 
  4023. pointer resource is that pointer are always the same size (determined by 
  4024. calling WinQuerySysValue with the SV_CXICON and SV_CYICON constants), while 
  4025. sprites can be any size, up to a maximum of MAX_SPRITE_CX by MAX_SPRITE_CY 
  4026. pels. 
  4027.  
  4028. Sprites are often used in animated sequences; however, while this group 
  4029. provides a basis for sprite manipulation, the animation is still up to the 
  4030. programmer to accomplish. 
  4031.  
  4032. Before a sprite can be drawn on the screen, it must belong to a playground.  A 
  4033. playground maintains a membership list and can have either a background bitmap 
  4034. or color associated with it.  Although the concept of a background seems 
  4035. superfluous, it is necessary for the transparency capabilities. 
  4036.  
  4037. Listed below are the functions which comprise this group: 
  4038.  
  4039. o CmnSprAddSprite 
  4040. o CmnSprCreatePlayground 
  4041. o CmnSprCreateSprite 
  4042. o CmnSprDestroyPlayground 
  4043. o CmnSprDestroySprite 
  4044. o CmnSprDrawPlayground 
  4045. o CmnSprDrawSprite 
  4046. o CmnSprQueryPlaygroundBack 
  4047. o CmnSprQueryPlaygroundColor 
  4048. o CmnSprQueryPlaygroundSize 
  4049. o CmnSprQuerySpritePosition 
  4050. o CmnSprQuerySpriteRect 
  4051. o CmnSprQuerySpriteSize 
  4052. o CmnSprQuerySpriteVisibility 
  4053. o CmnSprQueryUpdateFlag 
  4054. o CmnSprRemoveSprite 
  4055. o CmnSprSetPlaygroundBack 
  4056. o CmnSprSetPlaygroundColor 
  4057. o CmnSprSetPlaygroundSize 
  4058. o CmnSprSetSpritePosition 
  4059. o CmnSprSetSpriteVisibility 
  4060. o CmnSprSetUpdateFlag 
  4061.  
  4062.  
  4063. ΓòÉΓòÉΓòÉ 13.1. CmnSprAddSprite ΓòÉΓòÉΓòÉ
  4064.  
  4065. CmnSprAddSprite 
  4066.  
  4067. Purpose 
  4068.  
  4069. This function adds a sprite to a playground so that it may be drawn, moved, 
  4070. etc. 
  4071.  
  4072. Syntax 
  4073.  
  4074. (SPRERROR)CmnSprAddSprite(hpgPlay,hsSprite);
  4075.  
  4076. Parameters 
  4077.  
  4078. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4079.  
  4080. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4081.  
  4082. Returns 
  4083.  
  4084. This function returns one of the following values: 
  4085.  
  4086. SPR_ERR_NOERROR 
  4087. SPR_ERR_BADHANDLE 
  4088. SPR_ERR_HASPLAYGROUND 
  4089. SPR_ERR_PLAYGROUNDFULL 
  4090.  
  4091. Notes 
  4092.  
  4093. Once a sprite is added to a playground, it may not be destroyed until it is 
  4094. removed from the playground.  A sprite may belong to one playground only at any 
  4095. given time, and a playground can hold up to MAX_SPRITES number of sprites at 
  4096. any given time. 
  4097.  
  4098. Related information 
  4099.  
  4100. o HCSPLAYGROUND data type 
  4101. o HCSSPRITE data type 
  4102. o CmnSprCreateSprite 
  4103. o CmnSprDestroySprite 
  4104. o CmnSprRemoveSprite 
  4105.  
  4106.  
  4107. ΓòÉΓòÉΓòÉ 13.2. CmnSprCreatePlayground ΓòÉΓòÉΓòÉ
  4108.  
  4109. CmnSprCreatePlayground 
  4110.  
  4111. Purpose 
  4112.  
  4113. This function creates a playground instance to which sprites may be added. 
  4114.  
  4115. Syntax 
  4116.  
  4117. (SPRERROR)CmnSprCreatePlayground(habAnchor,phpgPlay);
  4118.  
  4119. Parameters 
  4120.  
  4121. habAnchor (HAB) - handle of the anchor block of the calling thread. 
  4122.  
  4123. phpgPlay (PHCSPLAYGROUND) - points to the variable to receive the handle of the 
  4124. playground. 
  4125.  
  4126. Returns 
  4127.  
  4128. This function returns one of the following values: 
  4129.  
  4130. SPR_ERR_NOERROR 
  4131. SPR_ERR_NOMEMORY 
  4132. SPR_ERR_RESOURCE 
  4133.  
  4134. Notes 
  4135.  
  4136. Although specifying an anchor block might imply otherwise, playground handles 
  4137. are not specific to a thread, but instead belong to the entire process. 
  4138.  
  4139. A playground is created with the following defaults: 
  4140.  
  4141. Update flag         TRUE 
  4142. Background          Color, which is CLR_BLACK 
  4143. Size                Height and width of 0 
  4144.  
  4145. Related information 
  4146.  
  4147. o HCSPLAYGROUND data type 
  4148. o CmnSprDestroyPlayground 
  4149.  
  4150.  
  4151. ΓòÉΓòÉΓòÉ 13.3. CmnSprCreateSprite ΓòÉΓòÉΓòÉ
  4152.  
  4153. CmnSprCreateSprite 
  4154.  
  4155. Purpose 
  4156.  
  4157. This function creates a sprite instance which may be added to a playground. 
  4158.  
  4159. Syntax 
  4160.  
  4161. (SPRERROR)CmnSprCreateSprite(habAnchor,hbmBitmap,phsSprite);
  4162.  
  4163. Parameters 
  4164.  
  4165. habAnchor (HAB) - handle of the anchor block of the calling thread. 
  4166.  
  4167. hbmBitmap (HBITMAP) - handle of the bitmap from which to create the sprite. 
  4168.  
  4169. phsSprite (PHCSSPRITE) - points to the variable to receive the handle of the 
  4170. sprite. 
  4171.  
  4172. Returns 
  4173.  
  4174. This function returns one of the following values: 
  4175.  
  4176. SPR_ERR_NOERROR 
  4177. SPR_ERR_BADHANDLE 
  4178. SPR_ERR_NOMEMORY 
  4179. SPR_ERR_RESOURCE 
  4180.  
  4181. Notes 
  4182.  
  4183. All pels in the bitmap that, once mapped to the physical palette, are black 
  4184. specify the transparent portions of the sprite.  The bitmap that is passed in 
  4185. cannot have a wider greater than MAX_SPRITE_CX pels or a height greater than 
  4186. MAX_SPRITE_CY or the function will fail with error SPR_ERR_BADHANDLE.  Once 
  4187. this function returns SPR_ERR_NOERROR, the bitmap handle (hbmBitmap) is 
  4188. considered to be owned by the sprite subsystem and should not be deleted by the 
  4189. application, unless by calling CmnSprDestroySprite. 
  4190.  
  4191. Like the playground, a sprite belongs to the entire process that created it, 
  4192. instead of just the thread as the anchor block parameter would imply. 
  4193.  
  4194. A sprite is created with the following defaults: 
  4195.  
  4196. Visibility          Not visible 
  4197. Position            (0,0) 
  4198.  
  4199. Related information 
  4200.  
  4201. o HCSSPRITE data type 
  4202. o CmnSprDestroySprite 
  4203.  
  4204.  
  4205. ΓòÉΓòÉΓòÉ 13.4. CmnSprDestroyPlayground ΓòÉΓòÉΓòÉ
  4206.  
  4207. CmnSprDestroyPlayground 
  4208.  
  4209. Purpose 
  4210.  
  4211. This function destroys the playground instance, all sprites that still belong 
  4212. to it, and the background bitmap if one exists. 
  4213.  
  4214. Syntax 
  4215.  
  4216. (SPRERROR)CmnSprDestroyPlayground(hpgPlay);
  4217.  
  4218. Parameters 
  4219.  
  4220. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4221.  
  4222. Returns 
  4223.  
  4224. This function returns one of the following values: 
  4225.  
  4226. SPR_ERR_NOERROR 
  4227. SPR_ERR_BADHANDLE 
  4228.  
  4229. Related information 
  4230.  
  4231. o HCSPLAYGROUND data type 
  4232. o CmnSprCreatePlayground 
  4233.  
  4234.  
  4235. ΓòÉΓòÉΓòÉ 13.5. CmnSprDestroySprite ΓòÉΓòÉΓòÉ
  4236.  
  4237. CmnSprDestroySprite 
  4238.  
  4239. Purpose 
  4240.  
  4241. This function destroys the sprite instance, including any associated bitmaps. 
  4242.  
  4243. Syntax 
  4244.  
  4245. (SPRERROR)CmnSprDestroySprite(hsSprite);
  4246.  
  4247. Parameters 
  4248.  
  4249. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4250.  
  4251. Returns 
  4252.  
  4253. This function returns one of the following values: 
  4254.  
  4255. SPR_ERR_NOERROR 
  4256. SPR_ERR_BADHANDLE 
  4257. SPR_ERR_HASPLAYGROUND 
  4258.  
  4259. Notes 
  4260.  
  4261. If the sprite still belongs to a playground, this function fails with the error 
  4262. SPR_ERR_HASPLAYGROUND. 
  4263.  
  4264. Related information 
  4265.  
  4266. o HCSSPRITE data type 
  4267. o CmnSprCreateSprite 
  4268.  
  4269.  
  4270. ΓòÉΓòÉΓòÉ 13.6. CmnSprDrawPlayground ΓòÉΓòÉΓòÉ
  4271.  
  4272. CmnSprDrawPlayground 
  4273.  
  4274. Purpose 
  4275.  
  4276. This function redraws the entire playground, including any sprites belonging to 
  4277. it. 
  4278.  
  4279. Syntax 
  4280.  
  4281. (SPRERROR)CmnSprDrawPlayground(hpsDraw,hpgPlay);
  4282.  
  4283. Parameters 
  4284.  
  4285. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4286.  
  4287. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4288.  
  4289. Returns 
  4290.  
  4291. This function returns one of the following values: 
  4292.  
  4293. SPR_ERR_NOERROR 
  4294. SPR_ERR_BADHANDLE 
  4295.  
  4296. Related information 
  4297.  
  4298. o HCSPLAYGROUND data type 
  4299. o CmnSprDrawSprite 
  4300.  
  4301.  
  4302. ΓòÉΓòÉΓòÉ 13.7. CmnSprDrawSprite ΓòÉΓòÉΓòÉ
  4303.  
  4304. CmnSprDrawSprite 
  4305.  
  4306. Purpose 
  4307.  
  4308. This function draws the sprite at its current position. 
  4309.  
  4310. Syntax 
  4311.  
  4312. (SPRERROR)CmnSprDrawSprite(hpsDraw,hsSprite);
  4313.  
  4314. Parameters 
  4315.  
  4316. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4317.  
  4318. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4319.  
  4320. Returns 
  4321.  
  4322. This function returns one of the following values: 
  4323.  
  4324. SPR_ERR_NOERROR 
  4325. SPR_ERR_BADHANDLE 
  4326. SPR_ERR_HASNOPLAYGROUND 
  4327.  
  4328. Notes 
  4329.  
  4330. If the sprite's visibility flag is FALSE (see CmnSprSetSpriteVisibility), this 
  4331. function returns SPR_ERR_NOERROR, but no drawing takes place. 
  4332.  
  4333. Changing the position or visibility state of the sprite automatically redraws 
  4334. the sprite without forcing you to call this function. 
  4335.  
  4336. Related information 
  4337.  
  4338. o HCSSPRITE data type 
  4339. o CmnSprDrawPlayground 
  4340.  
  4341.  
  4342. ΓòÉΓòÉΓòÉ 13.8. CmnSprQueryPlaygroundBack ΓòÉΓòÉΓòÉ
  4343.  
  4344. CmnSprQueryPlaygroundBack 
  4345.  
  4346. Purpose 
  4347.  
  4348. This function returns the handle of the playground background bitmap. 
  4349.  
  4350. Syntax 
  4351.  
  4352. (SPRERROR)CmnSprQueryPlaygroundBack(hpgPlay,phbmBack);
  4353.  
  4354. Parameters 
  4355.  
  4356. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4357.  
  4358. phbmBack (HBITMAP *) - points to the variable to receive the bitmap handle. 
  4359.  
  4360. Returns 
  4361.  
  4362. This function returns one of the following values: 
  4363.  
  4364. SPR_ERR_NOERROR 
  4365. SPR_ERR_BADHANDLE 
  4366.  
  4367. Notes 
  4368.  
  4369. The playground still owns the bitmap handle returned.  To specify that the 
  4370. playground should relinquish ownership, use the CmnSprSetPlaygroundBack 
  4371. function. 
  4372.  
  4373. Related information 
  4374.  
  4375. o HCSPLAYGROUND data type 
  4376. o CmnSprQueryPlaygroundColor 
  4377. o CmnSprQueryPlaygroundSize 
  4378. o CmnSprSetPlaygroundBack 
  4379. o CmnSprSetPlaygroundColor 
  4380. o CmnSprSetPlaygroundSize 
  4381.  
  4382.  
  4383. ΓòÉΓòÉΓòÉ 13.9. CmnSprQueryPlaygroundColor ΓòÉΓòÉΓòÉ
  4384.  
  4385. CmnSprQueryPlaygroundColor 
  4386.  
  4387. Purpose 
  4388.  
  4389. This function returns the current background color. 
  4390.  
  4391. Syntax 
  4392.  
  4393. (SPRERROR)CmnSprQueryPlaygroundColor(hpgPlay,plBackColor);
  4394.  
  4395. Parameters 
  4396.  
  4397. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4398.  
  4399. plBackColor (PLONG) - points to the variable to receive the current background 
  4400. color. 
  4401.  
  4402. Returns 
  4403.  
  4404. This function returns one of the following values: 
  4405.  
  4406. SPR_ERR_NOERROR 
  4407. SPR_ERR_BADHANDLE 
  4408. SPR_ERR_HASBACKGROUND 
  4409.  
  4410. Notes 
  4411.  
  4412. If the playground has a background bitmap, this function fails with the error 
  4413. SPR_ERR_HASBACKGROUND since the two are mutually exclusive properties. 
  4414.  
  4415. Related information 
  4416.  
  4417. o HCSPLAYGROUND data type 
  4418. o CmnSprQueryPlaygroundBack 
  4419. o CmnSprQueryPlaygroundSize 
  4420. o CmnSprSetPlaygroundBack 
  4421. o CmnSprSetPlaygroundColor 
  4422. o CmnSprSetPlaygroundSize 
  4423.  
  4424.  
  4425. ΓòÉΓòÉΓòÉ 13.10. CmnSprQueryPlaygroundSize ΓòÉΓòÉΓòÉ
  4426.  
  4427. CmnSprQueryPlaygroundSize 
  4428.  
  4429. Purpose 
  4430.  
  4431. This function returns the current background size. 
  4432.  
  4433. Syntax 
  4434.  
  4435. (SPRERROR)CmnSprQueryPlaygroundSize(hpgPlay,pszlSize);
  4436.  
  4437. Parameters 
  4438.  
  4439. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4440.  
  4441. pszlSize (PSIZEL) - points to the variable to receive the current background 
  4442. size. 
  4443.  
  4444. Returns 
  4445.  
  4446. This function returns one of the following values: 
  4447.  
  4448. SPR_ERR_NOERROR 
  4449. SPR_ERR_BADHANDLE 
  4450.  
  4451. Notes 
  4452.  
  4453. If the playground has a background bitmap, this function fails with the error 
  4454. SPR_ERR_HASBACKGROUND since the two are mutually exclusive properties. 
  4455.  
  4456. Related information 
  4457.  
  4458. o HCSPLAYGROUND data type 
  4459. o CmnSprQueryPlaygroundBack 
  4460. o CmnSprQueryPlaygroundColor 
  4461. o CmnSprSetPlaygroundBack 
  4462. o CmnSprSetPlaygroundColor 
  4463. o CmnSprSetPlaygroundSize 
  4464.  
  4465.  
  4466. ΓòÉΓòÉΓòÉ 13.11. CmnSprQuerySpritePosition ΓòÉΓòÉΓòÉ
  4467.  
  4468. CmnSprQuerySpritePosition 
  4469.  
  4470. Purpose 
  4471.  
  4472. This function returns the position of the sprite. 
  4473.  
  4474. Syntax 
  4475.  
  4476. (SPRERROR)CmnSprQuerySpritePosition(hsSprite,pptlPos);
  4477.  
  4478. Parameters 
  4479.  
  4480. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4481.  
  4482. pptlPos (PPOINTL) - points to the variable to receive the position of the 
  4483. sprite. 
  4484.  
  4485. Returns 
  4486.  
  4487. This function returns one of the following values: 
  4488.  
  4489. SPR_ERR_NOERROR 
  4490. SPR_ERR_BADHANDLE 
  4491. SPR_ERR_HASNOPLAYGROUND 
  4492.  
  4493. Notes 
  4494.  
  4495. The sprite must belong to a playground to have a position associated with it. 
  4496.  
  4497. Related information 
  4498.  
  4499. o HCSSPRITE data type 
  4500. o CmnSprAddSprite 
  4501. o CmnSprQuerySpriteRect 
  4502. o CmnSprQuerySpriteSize 
  4503. o CmnSprQuerySpriteVisibility 
  4504. o CmnSprRemoveSprite 
  4505. o CmnSprSetSpritePosition 
  4506. o CmnSprSetSpriteVisibility 
  4507.  
  4508.  
  4509. ΓòÉΓòÉΓòÉ 13.12. CmnSprQuerySpriteRect ΓòÉΓòÉΓòÉ
  4510.  
  4511. CmnSprQuerySpriteRect 
  4512.  
  4513. Purpose 
  4514.  
  4515. This function returns the bounding rectangle of the sprite. 
  4516.  
  4517. Syntax 
  4518.  
  4519. (SPRERROR)CmnSprQuerySpriteRect(hsSprite,prclRect);
  4520.  
  4521. Parameters 
  4522.  
  4523. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4524.  
  4525. prclRect (PRECTL) - points to the variable to receive the bounding rectangle of 
  4526. the sprite. 
  4527.  
  4528. Returns 
  4529.  
  4530. This function returns one of the following values: 
  4531.  
  4532. SPR_ERR_NOERROR 
  4533. SPR_ERR_BADHANDLE 
  4534. SPR_ERR_HASNOPLAYGROUND 
  4535.  
  4536. Notes 
  4537.  
  4538. The sprite must belong to a playground to have a position and size associated 
  4539. with it.  The bounding rectangle is calculated as follows: 
  4540.  
  4541. prclRect->xLeft=(current x position)
  4542. prclRect->yBottom=(current y position)
  4543. prclRect->xRight=prclRect->xLeft + (width of the original bitmap passed to
  4544.                                     CmnSprCreateSprite) - 1
  4545. prclRect->yTop=prclRect->yBottom + (height of the original bitmap passed to
  4546.                                     CmnSprCreateSprite) - 1
  4547.  
  4548. Related information 
  4549.  
  4550. o HCSSPRITE data type 
  4551. o CmnSprAddSprite 
  4552. o CmnSprQuerySpritePosition 
  4553. o CmnSprQuerySpriteSize 
  4554. o CmnSprQuerySpriteVisibility 
  4555. o CmnSprRemoveSprite 
  4556. o CmnSprSetSpritePosition 
  4557. o CmnSprSetSpriteVisibility 
  4558.  
  4559.  
  4560. ΓòÉΓòÉΓòÉ 13.13. CmnSprQuerySpriteSize ΓòÉΓòÉΓòÉ
  4561.  
  4562. CmnSprQuerySpriteSize 
  4563.  
  4564. Purpose 
  4565.  
  4566. This function returns the size of the sprite. 
  4567.  
  4568. Syntax 
  4569.  
  4570. (SPRERROR)CmnSprQuerySpriteSize(hsSprite,pszlSize);
  4571.  
  4572. Parameters 
  4573.  
  4574. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4575.  
  4576. pszlSize (PSIZEL) - points to the variable to receive the size of the sprite. 
  4577.  
  4578. Returns 
  4579.  
  4580. This function returns one of the following values: 
  4581.  
  4582. SPR_ERR_NOERROR 
  4583. SPR_ERR_BADHANDLE 
  4584.  
  4585. Notes 
  4586.  
  4587. Since the size of a sprite is static, this is the only function returning the 
  4588. value of a sprite characteristic which does not require the sprite to belong to 
  4589. a playground. 
  4590.  
  4591. Related information 
  4592.  
  4593. o HCSSPRITE data type 
  4594. o CmnSprAddSprite 
  4595. o CmnSprQuerySpritePosition 
  4596. o CmnSprQuerySpriteRect 
  4597. o CmnSprQuerySpriteVisibility 
  4598. o CmnSprRemoveSprite 
  4599. o CmnSprSetSpritePosition 
  4600. o CmnSprSetSpriteVisibility 
  4601.  
  4602.  
  4603. ΓòÉΓòÉΓòÉ 13.14. CmnSprQuerySpriteVisibility ΓòÉΓòÉΓòÉ
  4604.  
  4605. CmnSprQuerySpriteVisibility 
  4606.  
  4607. Purpose 
  4608.  
  4609. This function returns the visibility of the sprite. 
  4610.  
  4611. Syntax 
  4612.  
  4613. (SPRERROR)CmnSprQuerySpriteVisibility(hsSprite,pbVisible);
  4614.  
  4615. Parameters 
  4616.  
  4617. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4618.  
  4619. pbVisible (PBOOL) - points to the variable to receive the visibility state of 
  4620. the sprite. 
  4621.  
  4622. Returns 
  4623.  
  4624. This function returns one of the following values: 
  4625.  
  4626. SPR_ERR_NOERROR 
  4627. SPR_ERR_BADHANDLE 
  4628. SPR_ERR_HASNOPLAYGROUND 
  4629.  
  4630. Notes 
  4631.  
  4632. The sprite must belong to a playground to have a visibility state associated 
  4633. with it. 
  4634.  
  4635. Related information 
  4636.  
  4637. o HCSSPRITE data type 
  4638. o CmnSprAddSprite 
  4639. o CmnSprQuerySpritePosition 
  4640. o CmnSprQuerySpriteRect 
  4641. o CmnSprQuerySpriteSize 
  4642. o CmnSprRemoveSprite 
  4643. o CmnSprSetSpritePosition 
  4644. o CmnSprSetSpriteVisibility 
  4645.  
  4646.  
  4647. ΓòÉΓòÉΓòÉ 13.15. CmnSprQueryUpdateFlag ΓòÉΓòÉΓòÉ
  4648.  
  4649. CmnSprQueryUpdateFlag 
  4650.  
  4651. Purpose 
  4652.  
  4653. This function returns the value of the update flag of a playground. 
  4654.  
  4655. Syntax 
  4656.  
  4657. (SPRERROR)CmnSprQueryUpdateFlag(hpgPlay,pbUpdate);
  4658.  
  4659. Parameters 
  4660.  
  4661. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4662.  
  4663. pbUpdate (PBOOL) - points to the variable to receive the update flag of the 
  4664. playground. 
  4665.  
  4666. Returns 
  4667.  
  4668. This function returns one of the following values: 
  4669.  
  4670. SPR_ERR_NOERROR 
  4671. SPR_ERR_BADHANDLE 
  4672.  
  4673. Related information 
  4674.  
  4675. o HCSPLAYGROUND data type 
  4676. o CmnSprSetUpdateFlag 
  4677.  
  4678.  
  4679. ΓòÉΓòÉΓòÉ 13.16. CmnSprRemoveSprite ΓòÉΓòÉΓòÉ
  4680.  
  4681. CmnSprRemoveSprite 
  4682.  
  4683. Purpose 
  4684.  
  4685. This function removes a sprite from a playground. 
  4686.  
  4687. Syntax 
  4688.  
  4689. (SPRERROR)CmnSprRemoveSprite(hpgPlay,hsSprite);
  4690.  
  4691. Parameters 
  4692.  
  4693. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4694.  
  4695. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4696.  
  4697. Returns 
  4698.  
  4699. This function returns one of the following values: 
  4700.  
  4701. SPR_ERR_NOERROR 
  4702. SPR_ERR_BADHANDLE 
  4703. SPR_ERR_HASNOPLAYGROUND 
  4704.  
  4705. Notes 
  4706.  
  4707. This function must be called before the sprite can be destroyed. 
  4708.  
  4709. Related information 
  4710.  
  4711. o HCSPLAYGROUND data type 
  4712. o HCSSPRITE data type 
  4713. o CmnSprAddSprite 
  4714. o CmnSprCreateSprite 
  4715. o CmnSprDestroySprite 
  4716.  
  4717.  
  4718. ΓòÉΓòÉΓòÉ 13.17. CmnSprSetPlaygroundBack ΓòÉΓòÉΓòÉ
  4719.  
  4720. CmnSprSetPlaygroundBack 
  4721.  
  4722. Purpose 
  4723.  
  4724. This function sets the bitmap to be used for the background. 
  4725.  
  4726. Syntax 
  4727.  
  4728. (SPRERROR)CmnSprSetPlaygroundBack(hpgPlay,hbmNew,phbmOld);
  4729.  
  4730. Parameters 
  4731.  
  4732. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4733.  
  4734. hbmNew (HBITMAP) - handle of the new background bitmap. 
  4735.  
  4736. phbmOld (HBITMAP *) - points to the variable to receive the handle of current 
  4737. background bitmap.  This may be NULL. 
  4738.  
  4739. Returns 
  4740.  
  4741. This function returns one of the following values: 
  4742.  
  4743. SPR_ERR_NOERROR 
  4744. SPR_ERR_BADHANDLE 
  4745.  
  4746. Notes 
  4747.  
  4748. The playground also relinquishes ownership of the current background bitmap, 
  4749. meaning it becomes the application's responsibility to insure it is deleted 
  4750. before the application exits. 
  4751.  
  4752. Related information 
  4753.  
  4754. o HCSPLAYGROUND data type 
  4755. o CmnSprQueryPlaygroundBack 
  4756. o CmnSprQueryPlaygroundColor 
  4757. o CmnSprQueryPlaygroundSize 
  4758. o CmnSprSetPlaygroundColor 
  4759. o CmnSprSetPlaygroundSize 
  4760.  
  4761.  
  4762. ΓòÉΓòÉΓòÉ 13.18. CmnSprSetPlaygroundColor ΓòÉΓòÉΓòÉ
  4763.  
  4764. CmnSprSetPlaygroundColor 
  4765.  
  4766. Purpose 
  4767.  
  4768. This function sets the current background color. 
  4769.  
  4770. Syntax 
  4771.  
  4772. (SPRERROR)CmnSprSetPlaygroundColor(hpgPlay,lBackColor);
  4773.  
  4774. Parameters 
  4775.  
  4776. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4777.  
  4778. lBackColor (LONG) - specifies the new background color. 
  4779.  
  4780. Returns 
  4781.  
  4782. This function returns one of the following values: 
  4783.  
  4784. SPR_ERR_NOERROR 
  4785. SPR_ERR_BADHANDLE 
  4786. SPR_ERR_HASBACKGROUND 
  4787.  
  4788. Notes 
  4789.  
  4790. If the playground has a background bitmap, this function fails with error 
  4791. SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. 
  4792.  
  4793. Related information 
  4794.  
  4795. o HCSPLAYGROUND data type 
  4796. o CmnSprQueryPlaygroundBack 
  4797. o CmnSprQueryPlaygroundColor 
  4798. o CmnSprQueryPlaygroundSize 
  4799. o CmnSprSetPlaygroundBack 
  4800. o CmnSprSetPlaygroundSize 
  4801.  
  4802.  
  4803. ΓòÉΓòÉΓòÉ 13.19. CmnSprSetPlaygroundSize ΓòÉΓòÉΓòÉ
  4804.  
  4805. CmnSprSetPlaygroundSize 
  4806.  
  4807. Purpose 
  4808.  
  4809. This function sets the size of the playground. 
  4810.  
  4811. Syntax 
  4812.  
  4813. (SPRERROR)CmnSprSetPlaygroundSize(hpgPlay,pszlSize);
  4814.  
  4815. Parameters 
  4816.  
  4817. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4818.  
  4819. pszlSize (PSIZEL) - points to the variable specifying the new size of the 
  4820. playground. 
  4821.  
  4822. Returns 
  4823.  
  4824. This function returns one of the following values: 
  4825.  
  4826. SPR_ERR_NOERROR 
  4827. SPR_ERR_BADHANDLE 
  4828. SPR_ERR_HASBACKGROUND 
  4829.  
  4830. Notes 
  4831.  
  4832. If the playground has a background bitmap, this function fails with error 
  4833. SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. 
  4834.  
  4835. Related information 
  4836.  
  4837. o HCSPLAYGROUND data type 
  4838. o CmnSprQueryPlaygroundBack 
  4839. o CmnSprQueryPlaygroundColor 
  4840. o CmnSprQueryPlaygroundSize 
  4841. o CmnSprSetPlaygroundColor 
  4842. o CmnSprSetPlaygroundSize 
  4843.  
  4844.  
  4845. ΓòÉΓòÉΓòÉ 13.20. CmnSprSetSpritePosition ΓòÉΓòÉΓòÉ
  4846.  
  4847. CmnSprSetSpritePosition 
  4848.  
  4849. Purpose 
  4850.  
  4851. This function sets the position of the sprite. 
  4852.  
  4853. Syntax 
  4854.  
  4855. (SPRERROR)CmnSprSetSpritePosition(hpsDraw,hsSprite,pptlNew);
  4856.  
  4857. Parameters 
  4858.  
  4859. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4860.  
  4861. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4862.  
  4863. pptlNew (PPOINTL) - points to the variable specifying the new position. 
  4864.  
  4865. Returns 
  4866.  
  4867. This function returns one of the following values: 
  4868.  
  4869. SPR_ERR_NOERROR 
  4870. SPR_ERR_BADHANDLE 
  4871. SPR_ERR_HASNOPLAYGROUND 
  4872.  
  4873. Notes 
  4874.  
  4875. The algorithm used by this function is optimized to remove flicker when the 
  4876. bounding rectangle of the sprite at the current position overlaps the bounding 
  4877. rectangle of the sprite at the new position.  If the sprite is not visible, 
  4878. this function returns SPR_ERR_NOERROR. 
  4879.  
  4880. Related information 
  4881.  
  4882. o HCSSPRITE data type 
  4883. o CmnSprQuerySpritePosition 
  4884. o CmnSprQuerySpriteRect 
  4885. o CmnSprQuerySpriteSize 
  4886. o CmnSprQuerySpriteVisibility 
  4887. o CmnSprSetSpriteVisibility 
  4888.  
  4889.  
  4890. ΓòÉΓòÉΓòÉ 13.21. CmnSprSetSpriteVisibility ΓòÉΓòÉΓòÉ
  4891.  
  4892. CmnSprSetSpriteVisibility 
  4893.  
  4894. Purpose 
  4895.  
  4896. This function sets the visibility state of a sprite. 
  4897.  
  4898. Syntax 
  4899.  
  4900. (SPRERROR)CmnSprSetSpriteVisibility(hpsDraw,hsSprite,bVisible);
  4901.  
  4902. Parameters 
  4903.  
  4904. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4905.  
  4906. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4907.  
  4908. bVisible (BOOL) - specifies the new visibility state. 
  4909.  
  4910. Returns 
  4911.  
  4912. This function returns one of the following values: 
  4913.  
  4914. SPR_ERR_NOERROR 
  4915. SPR_ERR_BADHANDLE 
  4916. SPR_ERR_HASNOPLAYGROUND 
  4917.  
  4918. Related information 
  4919.  
  4920. o HCSSPRITE data type 
  4921. o CmnSprQuerySpritePosition 
  4922. o CmnSprQuerySpriteRect 
  4923. o CmnSprQuerySpriteSize 
  4924. o CmnSprQuerySpriteVisibility 
  4925. o CmnSprSetSpritePosition 
  4926.  
  4927.  
  4928. ΓòÉΓòÉΓòÉ 13.22. CmnSprSetUpdateFlag ΓòÉΓòÉΓòÉ
  4929.  
  4930. CmnSprSetUpdateFlag 
  4931.  
  4932. Purpose 
  4933.  
  4934. This function sets the update flag of the playground. 
  4935.  
  4936. Syntax 
  4937.  
  4938. (SPRERROR)CmnSprSetUpdateFlag(hpgPlay,bUpdate);
  4939.  
  4940. Parameters 
  4941.  
  4942. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4943.  
  4944. bUpdate (BOOL) - specifies the new update flag value. 
  4945.  
  4946. Returns 
  4947.  
  4948. This function returns one of the following values: 
  4949.  
  4950. SPR_ERR_NOERROR 
  4951. SPR_ERR_BADHANDLE 
  4952.  
  4953. Notes 
  4954.  
  4955. The update flag determines if any drawing actually takes place when any of the 
  4956. functions requiring a presentation space handle are called. 
  4957.  
  4958. Related information 
  4959.  
  4960. o HCSPLAYGROUND data type 
  4961. o CmnSprQueryUpdateFlag 
  4962.  
  4963.  
  4964. ΓòÉΓòÉΓòÉ 14. String routines ΓòÉΓòÉΓòÉ
  4965.  
  4966. The purpose of this group is to provide functions that manipulate strings which 
  4967. and are not provided by the C run time library. 
  4968.  
  4969. Listed below are the functions which comprise this group: 
  4970.  
  4971. o CmnStrConvertToNumber 
  4972. o CmnStrPadString 
  4973. o CmnStrParseCommandLine 
  4974. o CmnStrParseLine 
  4975. o CmnStrQueryWord 
  4976. o CmnStrQueryWordCount 
  4977. o CmnStrQueryWordLength 
  4978. o CmnStrQueryWordPosition 
  4979. o CmnStrStripSpace 
  4980.  
  4981.  
  4982. ΓòÉΓòÉΓòÉ 14.1. CmnStrConvertToNumber ΓòÉΓòÉΓòÉ
  4983.  
  4984. CmnStrConvertToNumber 
  4985.  
  4986. Purpose 
  4987.  
  4988. This function converts a string into its numerical equivalent. 
  4989.  
  4990. Syntax 
  4991.  
  4992. (BOOL)CmnStrConvertToNumber(pchString,pvResult,usType);
  4993.  
  4994. Parameters 
  4995.  
  4996. pchString (PCHAR) - points to the string to convert. 
  4997.  
  4998. pvResult (PVOID) - points to the buffer to receive the result. The size of this 
  4999. buffer depends on the SCTN_TYPE_ constant specified. 
  5000.  
  5001. usType (USHORT) - specifies a combination of one SCTN_TYPE_ constant and one 
  5002. SCTN_ATTR_ constant. 
  5003.  
  5004. Returns 
  5005.  
  5006. This function returns TRUE if successful, or FALSE otherwise. 
  5007.  
  5008. Notes 
  5009.  
  5010. Use CmnStrConvertToNumber to convert a string to a number.  This is preferable 
  5011. to atoi (atol, etc.) because this function returns a definitive indicator of 
  5012. success, whereas the ANSI functions simply return 0 when an error occurs (and 
  5013. this could be a valid value as well). 
  5014.  
  5015. Related information 
  5016.  
  5017. o SCTN_ constants 
  5018.  
  5019.  
  5020. ΓòÉΓòÉΓòÉ 14.2. CmnStrPadString ΓòÉΓòÉΓòÉ
  5021.  
  5022. CmnStrPadString 
  5023.  
  5024. Purpose 
  5025.  
  5026. This function pads a string with a specified character. 
  5027.  
  5028. Syntax 
  5029.  
  5030. (BOOL)CmnStrPadString(pchString,usSide,usLength,chPad);
  5031.  
  5032. Parameters 
  5033.  
  5034. pchString (PCHAR) - points to the string to pad. 
  5035.  
  5036. usSide (USHORT) - specifies the side to pad on as an SPS_ constant. 
  5037.  
  5038. usLength (USHORT) - specifies the desired length of the string. 
  5039.  
  5040. chPad (CHAR) - specifies the character to pad with. 
  5041.  
  5042. Returns 
  5043.  
  5044. This function returns TRUE if successful, or FALSE otherwise. 
  5045.  
  5046. Notes 
  5047.  
  5048. Use CmnStrPadString to pad a string to a specified length. 
  5049.  
  5050. Related information 
  5051.  
  5052. o SPS_ constants 
  5053.  
  5054.  
  5055. ΓòÉΓòÉΓòÉ 14.3. CmnStrParseCommandLine ΓòÉΓòÉΓòÉ
  5056.  
  5057. CmnStrParseCommandLine 
  5058.  
  5059. Purpose 
  5060.  
  5061. This function parses the command line arguments. 
  5062.  
  5063. Syntax 
  5064.  
  5065. (BOOL)CmnStrParseCommandLine(ppchArgs,
  5066.                              usNumArgs,
  5067.                              pccdFormat,
  5068.                              usNumSwitches,
  5069.                              pfnError);
  5070.  
  5071. Parameters 
  5072.  
  5073. ppchArgs (PCHAR *) - points to an array of pointers to the command line 
  5074. arguments. 
  5075.  
  5076. usNumArgs (USHORT) - specifies the number of arguments pointed to by ppchArgs. 
  5077.  
  5078. pccdFormat (PCSCMDDESC) - points to an array of CSCMDDESC structures describing 
  5079. the valid command line arguments. 
  5080.  
  5081. usNumSwitches (USHORT) - specifies the number of structures pointed to by 
  5082. pccdFormat. 
  5083.  
  5084. pfnError (PFNCMDERR) - points to a function which is called when an error 
  5085. occurs. 
  5086.  
  5087. Returns 
  5088.  
  5089. This function returns TRUE if successful, or FALSE otherwise. 
  5090.  
  5091. Notes 
  5092.  
  5093. Use CmnStrParseCommandLine to parse the command line arguments passed to the 
  5094. application.  For each argument that is described in pccdFormat, the 
  5095. corresponding function is called with the arguments to the command line 
  5096. argument (if any). 
  5097.  
  5098. pfnError is called whenever an error occurs while processing the command line. 
  5099. While this could be a syntax error (returned by the argument processing 
  5100. function), it could also be another error type (out of memory, etc.). 
  5101.  
  5102. Related information 
  5103.  
  5104. o CSCMDDESC data type 
  5105. o PFNCMDERR function 
  5106.  
  5107.  
  5108. ΓòÉΓòÉΓòÉ 14.4. CmnStrParseLine ΓòÉΓòÉΓòÉ
  5109.  
  5110. CmnStrParseLine 
  5111.  
  5112. Purpose 
  5113.  
  5114. This function parses a line of data containing fixed position, fixed length 
  5115. fields. 
  5116.  
  5117. Syntax 
  5118.  
  5119. (SHORT)CmnStrParseLine(pchLine,acFormat,usNumRecs,pbBuf);
  5120.  
  5121. Parameters 
  5122.  
  5123. pchLine (PCHAR) - points to the line to parse. 
  5124.  
  5125. pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing 
  5126. the fields in the line.  On return, the usType field indicates whether or not 
  5127. the field was empty. 
  5128.  
  5129. usNumRecs (USHORT) - specifies the number of structures pointed to by pcFormat. 
  5130.  
  5131. pbBuf (PBYTE) - points to the buffer to receive the results. On return, the 
  5132. buffer is initialized to the native equivalents of the fields (numeric, string, 
  5133. etc.). 
  5134.  
  5135. Returns 
  5136.  
  5137. This function returns the number of fields successfully parsed, or SPL_ERROR if 
  5138. an error occurred. 
  5139.  
  5140. Notes 
  5141.  
  5142. Use CmnStrParseLine to parse a line consisting of fixed position, fixed length 
  5143. fields similar to the sscanf function.  For example, supposing pchLine points 
  5144. to the following data: 
  5145.  
  5146. 12345This is a string678.90
  5147.  
  5148. Also, pcFormat points to four CSLINEDESC structures, containing the following 
  5149. values: 
  5150.  
  5151. {
  5152.    {
  5153.       0,
  5154.       5,
  5155.       SPL_TYPE_LONG
  5156.    },
  5157.    {
  5158.       21,
  5159.       6,
  5160.       SPL_TYPE_FLOAT
  5161.    },
  5162.    {
  5163.       5,
  5164.       16,
  5165.       SPL_TYPE_STRING
  5166.    },
  5167.    {
  5168.       28,
  5169.       4,
  5170.       SPL_TYPE_BYTE
  5171.    }
  5172. }
  5173. pbBuf points to a structure defined as follows: 
  5174.  
  5175. typedef struct {
  5176.    LONG lField1;
  5177.    float fField2;
  5178.    CHAR achField3[17];
  5179.    BYTE bField4;
  5180. } BUF, FAR *PBUF;
  5181.  
  5182. On exit, pbBuf points to the initialized structure containing 12345, 678.9, 
  5183. "This is a string", and (undefined), and the usType field of the CSLINEDESC 
  5184. structures will be SPL_FOUND, SPL_FOUND, SPL_FOUND, and SPL_NOT_FOUND (to 
  5185. indicate that there was not fourth field). 
  5186.  
  5187. It is imperative to note that if you are using this function, all structures 
  5188. initialized by this function must be "unaligned", i.e. no alignment of fields 
  5189. should be done by the compiler.  If you forget to specify this, unpredictable 
  5190. results will occur. 
  5191.  
  5192. Related information 
  5193.  
  5194. o SPL_ constants 
  5195. o CSLINEDESC data type 
  5196.  
  5197.  
  5198. ΓòÉΓòÉΓòÉ 14.5. CmnStrQueryWord ΓòÉΓòÉΓòÉ
  5199.  
  5200. CmnStrQueryWord 
  5201.  
  5202. Purpose 
  5203.  
  5204. This function returns the specified word in a string. 
  5205.  
  5206. Syntax 
  5207.  
  5208. (BOOL)CmnStrQueryWord(pchLine,sWord,pchWord,usSzWord);
  5209.  
  5210. Parameters 
  5211.  
  5212. pchLine (PCHAR) - points to the line to retrieve the word from. 
  5213.  
  5214. sWord (SHORT) - specifies the 0-based word number to retrieve. 
  5215.  
  5216. pchWord (PCHAR) - points to the buffer to receive the result. On return, the 
  5217. buffer contains the word retrieved. 
  5218.  
  5219. usSzWord (USHORT) - specifies the size of the buffer pointed to by pchWord. 
  5220.  
  5221. Returns 
  5222.  
  5223. This function returns TRUE if successful, or FALSE otherwise. 
  5224.  
  5225. Notes 
  5226.  
  5227. Use CmnStrQueryWord to retrieve a word from a line.  A word is defined as a 
  5228. sequence of letters, digits, and/or punctuation, delimited by whitespace. 
  5229.  
  5230. Related information 
  5231.  
  5232. o CmnStrQueryWordCount 
  5233. o CmnStrQueryWordLength 
  5234. o CmnStrQueryWordPosition 
  5235.  
  5236.  
  5237. ΓòÉΓòÉΓòÉ 14.6. CmnStrQueryWordCount ΓòÉΓòÉΓòÉ
  5238.  
  5239. CmnStrQueryWordCount 
  5240.  
  5241. Purpose 
  5242.  
  5243. This function queries the number of words in a line. 
  5244.  
  5245. Syntax 
  5246.  
  5247. (USHORT)CmnStrQueryWordCount(pchLine);
  5248.  
  5249. Parameters 
  5250.  
  5251. pchLine (PCHAR) - points to the line to query. 
  5252.  
  5253. Returns 
  5254.  
  5255. This function returns the number of words in the specified line. 
  5256.  
  5257. Notes 
  5258.  
  5259. Use CmnStrQueryWordCount to query the number of words in a line of ASCII data. 
  5260.  
  5261. Related information 
  5262.  
  5263. o CmnStrQueryWord 
  5264. o CmnStrQueryWordLength 
  5265. o CmnStrQueryWordPosition 
  5266.  
  5267.  
  5268. ΓòÉΓòÉΓòÉ 14.7. CmnStrQueryWordLength ΓòÉΓòÉΓòÉ
  5269.  
  5270. CmnStrQueryWordLength 
  5271.  
  5272. Purpose 
  5273.  
  5274. This function queries the length of a specified word in a line. 
  5275.  
  5276. Syntax 
  5277.  
  5278. (SHORT)CmnStrQueryWordLength(pchLine,sWord);
  5279.  
  5280. Parameters 
  5281.  
  5282. pchLine (PCHAR) - points to the line to query. 
  5283.  
  5284. sWord (SHORT) - specifies the number of the word to query. 
  5285.  
  5286. Returns 
  5287.  
  5288. This function returns the length of the specified word. 
  5289.  
  5290. Notes 
  5291.  
  5292. Use CmnStrQueryWordLength to query the length of a specified word in a line of 
  5293. ASCII data. 
  5294.  
  5295. Related information 
  5296.  
  5297. o CmnStrQueryWord 
  5298. o CmnStrQueryWordCount 
  5299. o CmnStrQueryWordPosition 
  5300.  
  5301.  
  5302. ΓòÉΓòÉΓòÉ 14.8. CmnStrQueryWordPosition ΓòÉΓòÉΓòÉ
  5303.  
  5304. CmnStrQueryWordPosition 
  5305.  
  5306. Purpose 
  5307.  
  5308. This function queries the position of a specified word in a line. 
  5309.  
  5310. Syntax 
  5311.  
  5312. (SHORT)CmnStrQueryWordPosition(pchLine,sWord);
  5313.  
  5314. Parameters 
  5315.  
  5316. pchLine (PCHAR) - points to the line to query. 
  5317.  
  5318. sWord (SHORT) - specifies the number of the word to query. 
  5319.  
  5320. Returns 
  5321.  
  5322. This function returns the 0-based index of the beginning of the specified word 
  5323. in the line. 
  5324.  
  5325. Notes 
  5326.  
  5327. Use CmnStrQueryWordPosition to query the position of a word in a line of ASCII 
  5328. data. 
  5329.  
  5330. Related information 
  5331.  
  5332. o CmnStrQueryWord 
  5333. o CmnStrQueryWordCount 
  5334. o CmnStrQueryWordLength 
  5335.  
  5336.  
  5337. ΓòÉΓòÉΓòÉ 14.9. CmnStrStripSpace ΓòÉΓòÉΓòÉ
  5338.  
  5339. CmnStrStripSpace 
  5340.  
  5341. Purpose 
  5342.  
  5343. This function strips the whitespace from the beginning and/or the end of a 
  5344. string. 
  5345.  
  5346. Syntax 
  5347.  
  5348. (BOOL)CmnStrStripSpace(pchString,usOptions);
  5349.  
  5350. Parameters 
  5351.  
  5352. pchString (PCHAR) - points to the string to strip. 
  5353.  
  5354. usOptions (USHORT) - specifies the side to strip from as an SPS_ constant. 
  5355.  
  5356. Returns 
  5357.  
  5358. This function returns TRUE if successful, or FALSE otherwise. 
  5359.  
  5360. Notes 
  5361.  
  5362. Use CmnStrStripSpace to strip the white space from a string. 
  5363.  
  5364. Related information 
  5365.  
  5366. o SPS_ constants 
  5367.  
  5368.  
  5369. ΓòÉΓòÉΓòÉ 15. Screen I/O routines ΓòÉΓòÉΓòÉ
  5370.  
  5371. The purpose of this group is to provide miscellaneous text-mode functions. 
  5372.  
  5373. Listed below are the functions which comprise this group: 
  5374.  
  5375. o CmnVioDisplayMessage 
  5376. o CmnVioGetString 
  5377. o CmnVioLoadMessage 
  5378.  
  5379.  
  5380. ΓòÉΓòÉΓòÉ 15.1. CmnVioDisplayMessage ΓòÉΓòÉΓòÉ
  5381.  
  5382. CmnVioDisplayMessage 
  5383.  
  5384. Purpose 
  5385.  
  5386. This function loads a message from a message file and writes it to stderr. 
  5387.  
  5388. Syntax 
  5389.  
  5390. (BOOL)CmnVioDisplayMessage(pchMsgFile,ulId,...);
  5391.  
  5392. Parameters 
  5393.  
  5394. pchMsgFile (PCHAR) - points to the name of the message file. Even if the 
  5395. message file is bound to the executable, this must be the name of the original 
  5396. message file. 
  5397.  
  5398. ulId (ULONG) - specifies the identifier of the message to load. 
  5399.  
  5400. ... (va_list) - specifies any additional arguments referred to by the message. 
  5401.  
  5402. Returns 
  5403.  
  5404. This function returns TRUE if successful, or FALSE otherwise. 
  5405.  
  5406. Notes 
  5407.  
  5408. Use CmnVioDisplayMessage to load and display a message from the specified 
  5409. message file.  Note that while fprintf will allow fields whose descriptors 
  5410. begin with a width specifier (e.g. "%05d%cdq.), this function does not since 
  5411. DosGetMessage attempts to substitute positional parameters when it encounters 
  5412. this. 
  5413.  
  5414.  
  5415. ΓòÉΓòÉΓòÉ 15.2. CmnVioGetString ΓòÉΓòÉΓòÉ
  5416.  
  5417. CmnVioLoadMessage 
  5418.  
  5419. Purpose 
  5420.  
  5421. This function gets a string from the user. 
  5422.  
  5423. Syntax 
  5424.  
  5425. (BOOL)CmnVioGetString(pchBuf,ulSzBuf,ulOptions);
  5426.  
  5427. Parameters 
  5428.  
  5429. pchBuf (PCHAR) - points to the buffer to hold the result.  On return, the 
  5430. buffer contains the string. 
  5431.  
  5432. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. 
  5433.  
  5434. ulOptions (ULONG) - one or more VGS_* constants. 
  5435.  
  5436. Returns 
  5437.  
  5438. This function returns TRUE if successful, or FALSE otherwise. 
  5439.  
  5440. Notes 
  5441.  
  5442. Use CmnVioGetString to get a string from the user.  The advantage of using this 
  5443. function instead of a C library function is that this function provides the 
  5444. following: 
  5445.  
  5446. o Cursor movement via left, right, Ctrl-left (word-left), Ctrl-right 
  5447.   (word-right). 
  5448.  
  5449. o Erase contents via Escape key. 
  5450.  
  5451. o Options for unreadable entry and input required. 
  5452.  
  5453. Related information 
  5454.  
  5455. o VGS_ constants 
  5456.  
  5457.  
  5458. ΓòÉΓòÉΓòÉ 15.3. CmnVioLoadMessage ΓòÉΓòÉΓòÉ
  5459.  
  5460. CmnVioLoadMessage 
  5461.  
  5462. Purpose 
  5463.  
  5464. This function loads a message from a message file. 
  5465.  
  5466. Syntax 
  5467.  
  5468. (BOOL)CmnVioLoadMessage(pchMsgFile,ulId,pchBuf,ulSzBuf);
  5469.  
  5470. Parameters 
  5471.  
  5472. pchMsgFile (PCHAR) - points to the name of the message file. Even if the 
  5473. message file is bound to the executable, this must be the name of the original 
  5474. message file. 
  5475.  
  5476. ulId (ULONG) - specifies the identifier of the message to load. 
  5477.  
  5478. pchBuf (PCHAR) - points to the buffer to receive the result. On return, the 
  5479. buffer contains the loaded message. 
  5480.  
  5481. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. 
  5482.  
  5483. Returns 
  5484.  
  5485. This function returns TRUE if successful, or FALSE otherwise. 
  5486.  
  5487. Notes 
  5488.  
  5489. Use CmnVioLoadMessage to load a message from the specified message file.  Note 
  5490. that it is impossible to have a message with simply a carriage-return at the 
  5491. end (versus a carriage-return, line-feed pair), since the toolkit utility 
  5492. MKMSGF indicates this to be a syntax error. 
  5493.  
  5494.  
  5495. ΓòÉΓòÉΓòÉ 16. Windowing routines ΓòÉΓòÉΓòÉ
  5496.  
  5497. The purpose of this group is to provide miscellaneous windowing functions. 
  5498.  
  5499. Listed below are the functions which comprise this group: 
  5500.  
  5501. o CmnWinCenterWindow 
  5502. o CmnWinDisplayMessage 
  5503. o CmnWinRestorePosition 
  5504. o CmnWinRestorePosFromBuffer 
  5505. o CmnWinSavePosition 
  5506. o CmnWinSavePosToBuffer 
  5507.  
  5508.  
  5509. ΓòÉΓòÉΓòÉ 16.1. CmnWinCenterWindow ΓòÉΓòÉΓòÉ
  5510.  
  5511. CmnWinCenterWindow 
  5512.  
  5513. Purpose 
  5514.  
  5515. This function centers a window within its parent. 
  5516.  
  5517. Syntax 
  5518.  
  5519. (VOID)CmnWinCenterWindow(hwndCenter);
  5520.  
  5521. Parameters 
  5522.  
  5523. hwndCenter (HWND) - specifies the handle of the window to center. 
  5524.  
  5525. Notes 
  5526.  
  5527. Use CmnWinCenterWindow to center a window within its parent. 
  5528.  
  5529.  
  5530. ΓòÉΓòÉΓòÉ 16.2. CmnWinDisplayMessage ΓòÉΓòÉΓòÉ
  5531.  
  5532. CmnWinDisplayMessage 
  5533.  
  5534. Purpose 
  5535.  
  5536. This function loads a message from the STRINGTABLE and displays it in a message 
  5537. box. 
  5538.  
  5539. Syntax 
  5540.  
  5541. (SHORT)CmnWinDisplayMessage(hwndParent,
  5542.                             hwndOwner,
  5543.                             ulStyle,
  5544.                             hmDll,
  5545.                             usId,
  5546.                             usHelpId,
  5547.                             ...);
  5548.  
  5549. Parameters 
  5550.  
  5551. hwndParent (HWND) - specifies the handle of the parent window. 
  5552.  
  5553. hwndOwner (HWND) - specifies the handle of the owner window. 
  5554.  
  5555. ulStyle (ULONG) - specifies the style of the message box.  If 0 is specified, 
  5556. MB_INFORMATION | MB_OK is used. 
  5557.  
  5558. hmDll (HMODULE) - specifies the handle to the module containing the STRINGTABLE 
  5559. to load from (or NULL if the .EXE file contains the STRINGTABLE). 
  5560.  
  5561. usId (USHORT) - specifies the identifier of the message to load. 
  5562.  
  5563. usHelpId (USHORT) - specifies the identifier that is used when calling the help 
  5564. hook.  If this is 0, no help button is shown in the message box. 
  5565.  
  5566. ... (va_list) - specifies any additional arguments referred to by the message. 
  5567.  
  5568. Returns 
  5569.  
  5570. This function returns the same result as WinMessageBox. 
  5571.  
  5572. Notes 
  5573.  
  5574. Use CmnWinDisplayMessage to load a message and display it on the screen. 
  5575.  
  5576.  
  5577. ΓòÉΓòÉΓòÉ 16.3. CmnWinRestorePosition ΓòÉΓòÉΓòÉ
  5578.  
  5579. CmnWinRestorePosition 
  5580.  
  5581. Purpose 
  5582.  
  5583. This function restores the position of a window previously saved with 
  5584. CmnWinSavePosition. 
  5585.  
  5586. Syntax 
  5587.  
  5588. (BOOL)CmnWinRestorePosition(hwndWindow,
  5589.                             hiniProfile,
  5590.                             pchAppl,
  5591.                             pchKey);
  5592.  
  5593. Parameters 
  5594.  
  5595. hwndWindow (HWND) - specifies the handle of the window to restore. 
  5596.  
  5597. hiniProfile (HINI) - specifies the .INI file handle containing the saved 
  5598. position information. 
  5599.  
  5600. pchAppl (PCHAR) - points to the application name that the positional 
  5601. information was saved under. 
  5602.  
  5603. pchKey (PCHAR) - points to the key name that the positional information was 
  5604. saved under. 
  5605.  
  5606. Returns 
  5607.  
  5608. This function returns TRUE if successful, or FALSE otherwise. 
  5609.  
  5610. Notes 
  5611.  
  5612. Use CmnWinRestorePosition to restore the position of a window previously saved 
  5613. with CmnWinSavePosition.  For MDI applications, you should use the 
  5614. CmnWinSavePosToBuffer and CmnWinRestorePosFromBuffer function. 
  5615.  
  5616. Related information 
  5617.  
  5618. o CmnWinSavePosition 
  5619.  
  5620.  
  5621. ΓòÉΓòÉΓòÉ 16.4. CmnWinRestorePosFromBuffer ΓòÉΓòÉΓòÉ
  5622.  
  5623. CmnWinRestorePosFromBuffer 
  5624.  
  5625. Purpose 
  5626.  
  5627. This function restores the position of a window previously saved with 
  5628. CmnWinSavePosToBuffer. 
  5629.  
  5630. Syntax 
  5631.  
  5632. BOOL CmnWinRestorePosFromBuffer(hwndWindow,pcpPosition);
  5633.  
  5634. Parameters 
  5635.  
  5636. hwndWindow (HWND) - the handle of the window to restore 
  5637.  
  5638. pcpPosition (PCWPOSITION) - points to the variable containing the information 
  5639. to be used when restoring 
  5640.  
  5641. Returns 
  5642.  
  5643. This function returns TRUE if successful, or FALSE otherwise. 
  5644.  
  5645. Notes 
  5646.  
  5647. Use CmnWinRestorePosFromBuffer to restore a window's size and position from the 
  5648. information saved by CmnWinSavePosToBuffer. 
  5649.  
  5650. Related information 
  5651.  
  5652. o CWPOSITION data type 
  5653. o CmnWinSavePosToBuffer 
  5654.  
  5655.  
  5656. ΓòÉΓòÉΓòÉ 16.5. CmnWinSavePosition ΓòÉΓòÉΓòÉ
  5657.  
  5658. CmnWinSavePosition 
  5659.  
  5660. Purpose 
  5661.  
  5662. This function saves the position of a window to be restored later with 
  5663. CmnWinRestorePosition. 
  5664.  
  5665. Syntax 
  5666.  
  5667. (BOOL)CmnWinSavePosition(hwndWindow,
  5668.                          hiniProfile,
  5669.                          pchAppl,
  5670.                          pchKey);
  5671.  
  5672. Parameters 
  5673.  
  5674. hwndWindow (HWND) - specifies the handle of the window to restore. 
  5675.  
  5676. hiniProfile (HINI) - specifies the .INI file handle to which the saved position 
  5677. information will be written. 
  5678.  
  5679. pchAppl (PCHAR) - points to the application name that the positional 
  5680. information will be saved under. 
  5681.  
  5682. pchKey (PCHAR) - points to the key name that the positional information will be 
  5683. saved under. 
  5684.  
  5685. Returns 
  5686.  
  5687. This function returns TRUE if successful, or FALSE otherwise. 
  5688.  
  5689. Notes 
  5690.  
  5691. Use CmnWinSavePosition to save the current size and position of the specified 
  5692. window for restoration at a later time. 
  5693.  
  5694. Related information 
  5695.  
  5696. o CmnWinRestorePosition 
  5697.  
  5698.  
  5699. ΓòÉΓòÉΓòÉ 16.6. CmnWinSavePosToBuffer ΓòÉΓòÉΓòÉ
  5700.  
  5701. CmnWinSavePosToBuffer 
  5702.  
  5703. Purpose 
  5704.  
  5705. This function saves the position of a window to a buffer for later use with 
  5706. CmnWinRestorePosFromBuffer. 
  5707.  
  5708. Syntax 
  5709.  
  5710. BOOL CmnWinSavePosToBuffer(hwndWindow,pcpPosition);
  5711.  
  5712. Parameters 
  5713.  
  5714. hwndWindow (HWND) - the handle of the window to restore 
  5715.  
  5716. pcpPosition (PCWPOSITION) - points to the variable to contain the information 
  5717. to be used when restoring 
  5718.  
  5719. Returns 
  5720.  
  5721. This function returns TRUE if successful, or FALSE otherwise. 
  5722.  
  5723. Notes 
  5724.  
  5725. Use CmnWinSavePosToBuffer to save a window's size and position so that it can 
  5726. be later restored using CmnWinRestorePosFromBuffer. 
  5727.  
  5728. Related information 
  5729.  
  5730. o CWPOSITION data type 
  5731. o CmnWinRestorePosFromBuffer 
  5732.  
  5733.  
  5734. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5735.  
  5736. Constant                      Meaning 
  5737. CCI_TYPE_CLIENT               Specifies that the connection type is (to be) 
  5738.                               client. 
  5739. CCI_TYPE_SERVER               Specifies that the connection type is (to be) 
  5740.                               server. 
  5741. CCI_TYPE_SERVERCONNECT        Specifies that the connection type is a server 
  5742.                               data connection to a client.  This can never be 
  5743.                               specified for CmnComOpenConnection. 
  5744. CCI_TYPE_CLIENTSERVER         Specifies that the connection type is (to be) 
  5745.                               client or server. 
  5746. CCI_ATTR_NOACKS               Specifies that no acknowledgements are to be 
  5747.                               requested by CmnComWriteData.  This is useful for 
  5748.                               eliminating overhead for transaction-based 
  5749.                               protocols where the applications must implement 
  5750.                               their own acknowledgements. 
  5751.  
  5752.  
  5753. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5754.  
  5755. Constant                      Meaning 
  5756. CSC_CLOSE                     specifies that the connection should be closed. 
  5757. CSC_RESET                     specifies that the connection should be reset. 
  5758.                               "Reset" is an abstract term that is defined by 
  5759.                               the application. 
  5760.  
  5761.  
  5762. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5763.  
  5764. A 32-bit handle used to specify a connection.  This handle is created by either 
  5765. CmnComOpenConnection or CmnComWaitConnection and is destroyed by 
  5766. CmnComCloseConnection. 
  5767.  
  5768. Related information 
  5769.  
  5770. o CmnComCloseConnection 
  5771. o CmnComOpenConnection 
  5772. o CmnComWaitConnection 
  5773.  
  5774.  
  5775. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5776.  
  5777. typedef struct _CCOPENINFO {
  5778.    CHAR achMachine[MAX_CONNECTNAME+1];
  5779.    CHAR achConnect[MAX_CONNECTNAME+1];
  5780.    USHORT usAttr;
  5781.    LONG lTimeout;
  5782. } CCOPENINFO, FAR *PCCOPENINFO;
  5783.  
  5784. achMachine                    Specifies the name of the remote machine to 
  5785.                               connect to.  If this is an empty string, the 
  5786.                               connection is created locally. 
  5787. achConnect                    Specifies the name of the connection. 
  5788. usAttr                        Specifies a CCI_TYPE_* constant and zero or more 
  5789.                               CCI_ATTR_* constants. 
  5790. lTimeout                      Specifies the timeout, in seconds, for 
  5791.                               connections, data reading, and acknowledgement 
  5792.                               waiting. If this value is CCI_ATTR_NOTIMEOUT, no 
  5793.                               timeout will occur. 
  5794.  
  5795. Related information 
  5796.  
  5797. o CCI_ constants 
  5798.  
  5799.  
  5800. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5801.  
  5802. typedef struct _CCCONNECTINFO {
  5803.    CHAR achConnect[MAX_CONNECTNAME+1];
  5804.    USHORT usAttr;
  5805.    ULONG ulSzData;
  5806.    LONG lTimeout;
  5807. } CCCONNECTINFO, FAR *PCCCONNECTINFO;
  5808.  
  5809. achConnect                    Specifies the fully qualified name of the 
  5810.                               connection.  For clients, this will not be the 
  5811.                               name of the connection specified in the 
  5812.                               CCOPENINFO structure on the call to 
  5813.                               CmnComOpenConnection. 
  5814. usAttr                        Specifies the type of the connection and any 
  5815.                               associated attributes.  These are defined as CCI_ 
  5816.                               constants. 
  5817. ulSzData                      Specifies the size, in bytes, of any data waiting 
  5818.                               to be read.  This is the same value that is 
  5819.                               returned by CmnComQueryData. 
  5820. lTimeout                      Specifies the timeout value, in seconds. 
  5821.  
  5822. For calls to CmnSetHandleInfo, lTimeout is the only field that is used.  All 
  5823. others are ignored. 
  5824.  
  5825. Related information 
  5826.  
  5827. o CCI_ constants 
  5828. o CmnSetHandleInfo 
  5829. o CmnComOpenConnection 
  5830. o CmnComQueryData 
  5831.  
  5832.  
  5833. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5834.  
  5835. Constant                      Meaning 
  5836. DWT_TYPE_NAME                 specifies that the file argument points to the 
  5837.                               file name 
  5838. DWT_TYPE_FILE                 specifies that the file argument points to a FILE 
  5839.                               structure 
  5840.  
  5841.  
  5842. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5843.  
  5844. Constant                      Meaning 
  5845. FCS_ATTR_NORMAL               specifies normal files 
  5846. FCS_ATTR_READONLY             specifies read-only files 
  5847. FCS_ATTR_HIDDEN               specifies hidden files 
  5848. FCS_ATTR_SYSTEM               specifies system files 
  5849. FCS_ATTR_DIRECTORY            specifies directories 
  5850. FCS_ATTR_ARCHIVED             specifies archived files 
  5851.  
  5852.  
  5853. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5854.  
  5855. Constant                      Meaning 
  5856. FEA_TYPE                      specifes the "Type" extended attribute 
  5857. FEA_KEYPHRASES                specifes the "Key phrases" extended attribute 
  5858. FEA_SUBJECT                   specifes the "Subject" extended attribute 
  5859. FEA_COMMENTS                  specifes the "Comments" extended attribute 
  5860. FEA_HISTORY                   specifes the "History" extended attribute 
  5861. FEA_VERSION                   specifes the "Version" extended attribute 
  5862. FEA_ICON                      specifes the "Icon" extended attribute 
  5863. FEA_ASSOCTABLE                specifes the "Assoctable" extended attribute 
  5864. FEA_HPFSNAME                  specifes the "HPFS name" extended attribute 
  5865.  
  5866.  
  5867. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5868.  
  5869. Constant                      Meaning 
  5870. FCD_OPT_WANTFORMATTED         specifies that the function should fail if the 
  5871.                               destination diskette is not already formatted. 
  5872.                               If this option is not specified, and the 
  5873.                               destination diskette is not formatted, 
  5874.                               CmnFilFormatDiskette is called to format the 
  5875.                               diskette. 
  5876.  
  5877. Related information 
  5878.  
  5879. o CmnFilFormatDiskette 
  5880.  
  5881.  
  5882. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5883.  
  5884. Constant                      Meaning 
  5885. FCD_TYPE_ERROR                specifies that the value of the second parameter 
  5886.                               of pfnCallback is an FCD_ERR_* constant. 
  5887. FCD_TYPE_MESSAGE              specifies that the value of the second parameter 
  5888.                               of pfnCallback is an FCD_MSG_* constant.  The 
  5889.                               return value of pfnCallback is determined by this 
  5890.                               FCD_MSG_* constant. 
  5891. FCD_TYPE_PROGRESS             specifies that the value of the second parameter 
  5892.                               of pfnCallback is a number in the range 0-100 
  5893.                               which specifies the percentage complete of the 
  5894.                               current operation (read, write, etc.). 
  5895.  
  5896.  
  5897. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5898.  
  5899. Constant                      Meaning 
  5900. FCD_MSG_BEGINFORMAT           specifies that the format operation is beginning. 
  5901. FCD_MSG_BEGINREAD             specifies that the read of the source diskette is 
  5902.                               beginning. 
  5903. FCD_MSG_BEGINVERIFY           specifies that the verify of the destination 
  5904.                               diskette is beginning. 
  5905. FCD_MSG_BEGINWRITE            specifies that the write of the destination 
  5906.                               diskette is beginning. 
  5907. FCD_MSG_ENDFORMAT             specifies that the format operation has completed 
  5908.                               successfully. 
  5909. FCD_MSG_ENDREAD               specifies that the source diskette was 
  5910.                               successfully read. 
  5911. FCD_MSG_ENDVERIFY             specifies that the destination diskette was 
  5912.                               successfully verified. 
  5913. FCD_MSG_ENDWRITE              specifies that the destination diskette was 
  5914.                               successfully written. 
  5915. FCD_MSG_SIZEMISMATCH          specifies that the source and destination 
  5916.                               diskette sizes do not match. pfnCallback should 
  5917.                               return TRUE if a new diskette has been inserted 
  5918.                               and the operation should be retried or FALSE if 
  5919.                               the copy operation should be halted. 
  5920. FCD_MSG_UNFORMATTED           specifies that the destination diskette is 
  5921.                               unformatted and FCD_OPT_WANTFORMATTED was 
  5922.                               specified.  pfnCallback should return TRUE if a 
  5923.                               new, formatted diskette has been inserted and the 
  5924.                               operation should be retried, or FALSE if the 
  5925.                               operation is to be aborted. 
  5926. FCD_MSG_VALIDATESRCDISK       specifies that pfnCallback should verify that the 
  5927.                               source diskette is the desired one to be copied. 
  5928.                               This is usually done by calling CmnFilQueryLabel 
  5929.                               to check the diskette label. pfnCallback should 
  5930.                               return TRUE if the correct diskette is in the 
  5931.                               drive or FALSE otherwise.  Returning FALSE causes 
  5932.                               CmnFilCopyDiskette to resend the 
  5933.                               FCD_MSG_WANTSRCDISK message. 
  5934. FCD_MSG_WANTDESTDISK          specifies that the destination diskette should be 
  5935.                               inserted in the drive. This is sent if the source 
  5936.                               and destination drives are the same and the 
  5937.                               source diskette was successfully read or if there 
  5938.                               is no diskette in the destination drive. 
  5939.                               pfnCallback should return TRUE if the diskette 
  5940.                               has been inserted and the operation should be 
  5941.                               retried or FALSE if the copy operation should be 
  5942.                               halted. 
  5943. FCD_MSG_WANTFORMATDISK        specifies that the diskette to be formatted 
  5944.                               should be inserted in the drive.  pfnCallback 
  5945.                               should return TRUE if the diskette has been 
  5946.                               inserted and the operation should be retried or 
  5947.                               FALSE if the format operation should be halted. 
  5948. FCD_MSG_WANTSRCDISK           specifies that the source diskette should be 
  5949.                               inserted in the drive.  This is sent if there is 
  5950.                               no diskette in the destination drive. pfnCallback 
  5951.                               should return TRUE if the diskette has been 
  5952.                               inserted and the operation should be retried or 
  5953.                               FALSE if the copy operation should be halted. 
  5954. FCD_MSG_WRITEPROTECTED        specifies that the destination diskette is 
  5955.                               write-protected. pfnCallback should return TRUE 
  5956.                               if this condition has been corrected and the 
  5957.                               operation should be retried or FALSE if the copy 
  5958.                               operation should be halted. 
  5959.  
  5960.  
  5961. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5962.  
  5963. Constant                      Meaning 
  5964. FCD_ERR_ABORTED               specifies that the operation was halted because 
  5965.                               pfnCallback returned FALSE for an FCD_MSG_* 
  5966.                               constant whose return value is significant. 
  5967. FCD_ERR_CLOSEFAILED           specifies that an attempt to close the diskette 
  5968.                               failed. 
  5969. FCD_ERR_DESTDRVINVALID        specifies that the destination drive specified 
  5970.                               does not support removable media. 
  5971. FCD_ERR_FORMATFAILED          specifies that the format operation failed. 
  5972. FCD_ERR_LOCKFAILED            specifies that either the source or destination 
  5973.                               drive could not be "locked". 
  5974. FCD_ERR_NOMEMORY              specifies that there is not enough memory to hold 
  5975.                               the contents of the source diskette. 
  5976. FCD_ERR_OPENFAILED            specifies that an attempt to open the diskette 
  5977.                               failed. 
  5978. FCD_ERR_READFAILED            specifies that a read operation failed. 
  5979. FCD_ERR_SRCDRVINVALID         specifies that the source drive specified does 
  5980.                               not support removable media. 
  5981. FCD_ERR_UNLOCKFAILED          specifies that either the source or destination 
  5982.                               drive could not be "unlocked". 
  5983. FCD_ERR_VERIFYFAILED          specifies that the verify operation failed. 
  5984. FCD_ERR_WRITEFAILED           specifies that a write operation failed. 
  5985.  
  5986.  
  5987. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5988.  
  5989. A 32-bit handle used for file searches.  It is created using the function 
  5990. CmnFilCreateSearch and is destroyed using the function CmnFilDestroySearch. 
  5991.  
  5992. Related information 
  5993.  
  5994. o CmnFilCreateSearch 
  5995. o CmnFilDestroySearch 
  5996.  
  5997.  
  5998. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5999.  
  6000. Constant                      Meaning 
  6001. CFFI_SECTOR_128B              specifies 128 bytes per sector 
  6002. CFFI_SECTOR_256B              specifies 256 bytes per sector 
  6003. CFFI_SECTOR_512B              specifies 512 bytes per sector 
  6004. CFFI_SECTOR_1024B             specifies 1024 bytes per sector 
  6005.  
  6006.  
  6007. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6008.  
  6009. Format parameters 
  6010.  
  6011. typedef struct _CFFORMATINFO {
  6012.    ULONG ulSzStruct;
  6013.    ULONG ulNumTracks;
  6014.    ULONG ulNumSectors;
  6015.    ULONG ulSzSector;
  6016. } CFFORMATINFO, *PCFFORMATINFO;
  6017.  
  6018. ulSzStruct                    specifies the size of the structure in bytes. 
  6019. ulNumTracks                   specifies the desired number of tracks. 
  6020. ulNumSectors                  specifies the number of sectors per track. 
  6021. ulSzSector                    specifies a CFFI_SECTOR_* constant describing the 
  6022.                               size of each sector. 
  6023.  
  6024. Standard formats are listed below: 
  6025.  
  6026. 360 KB (5.25 inch)            ulNumTracks=40, ulNumSectors=9, 
  6027.                               ulSzSector=CFFI_SECTOR_512B 
  6028. 720 KB (3.5 inch)             ulNumTracks=80, ulNumSectors=9, 
  6029.                               ulSzSector=CFFI_SECTOR_512B 
  6030. 1.2 MB (5.25 inch)            ulNumTracks=80, ulNumSectors=15, 
  6031.                               ulSzSector=CFFI_SECTOR_512B 
  6032. 1.44 MB (3.5 inch)            ulNumTracks=80, ulNumSectors=18, 
  6033.                               ulSzSector=CFFI_SECTOR_512B 
  6034. 2.88 MB (3.5 inch)            ulNumTracks=80, ulNumSectors=36, 
  6035.                               ulSzSector=CFFI_SECTOR_512B 
  6036.  
  6037. It is recommended that your application use a standard format since unexpected 
  6038. results may occur otherwise (due to limitations in the file system drivers 
  6039. and/or hardware). 
  6040.  
  6041. Related information 
  6042.  
  6043. o CFFI_SECTOR_ constants 
  6044.  
  6045.  
  6046. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6047.  
  6048. typedef BOOL (* EXPENTRY PFNDISKIO)(ULONG,ULONG,PVOID);
  6049.  
  6050. Input 
  6051.  
  6052. ULONG               specifies an FCD_TYPE_* constant which describes how the 
  6053.                     next parameter is to be interpreted. 
  6054. ULONG               depending on the value of the last parameter: 
  6055.  
  6056.    FCD_TYPE_PROGRESS   specifies a value in the range 0-100 which specifies the 
  6057.                        progress of the copy operation. 
  6058.    FCD_TYPE_MESSAGE    specifies an FCD_MSG_* constant. 
  6059.    FCD_TYPE_ERROR      specifies an FCD_ERR_* constant. 
  6060. PVOID               specifies the user data passed to the CmnFilCopyDiskette 
  6061.                     function. 
  6062.  
  6063. For FCF_TYPE_PROGRESS, this function returns TRUE if the operation is to 
  6064. continue, or FALSE if the operation is to be halted.  For FCD_TYPE_MESSAGE, the 
  6065. return value may or may not be significant, depending on the specific FCD_MSG_* 
  6066. constant passed. 
  6067.  
  6068. Related information 
  6069.  
  6070. o FCD_TYPE_ constants 
  6071. o FCD_MSG_ constants 
  6072. o FCD_ERR_ constants 
  6073.  
  6074.  
  6075. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6076.  
  6077. Constant                      Meaning 
  6078. LAR_TAIL                      specifies that the record should be inserted at 
  6079.                               the end of the list. 
  6080. LAR_HEAD                      specifies that the record should be inserted at 
  6081.                               the beginning of the list. 
  6082.  
  6083.  
  6084. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6085.  
  6086. Constant                      Meaning 
  6087. LQR_END                       specifies that the last record should be returned 
  6088. LQR_PREVIOUS                  specifies that the previous record should be 
  6089.                               returned 
  6090. LQR_NEXT                      specifies that the next record should be returned 
  6091.  
  6092.  
  6093. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6094.  
  6095. A 32-bit handle used to specify a linked list.  It is created using the 
  6096. function CmnLstCreateList and is destroyed using the function 
  6097. CmnLstDestroyList. 
  6098.  
  6099. Related information 
  6100.  
  6101. o CmnLstCreateList 
  6102. o CmnLstDestroyList 
  6103.  
  6104.  
  6105. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6106.  
  6107. typedef struct _CLLISTINFO {
  6108.    USHORT usSzRecord;
  6109.    USHORT usNumRecords;
  6110.    PVOID pvHead;
  6111.    PVOID pvTail;
  6112. } CLLISTINFO, FAR *PCLLISTINFO;
  6113.  
  6114. usSzRecord                    Contains the size of each record in the list. 
  6115. usNumRecords                  Contains the number of records currently in the 
  6116.                               list. 
  6117. pvHead                        Points to the head of the list. 
  6118. pvTail                        Points to the tail of the list. 
  6119.  
  6120.  
  6121. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6122.  
  6123. typedef SHORT (* EXPENTRY PFNRECCOMP)(PVOID,PVOID);
  6124.  
  6125. Input 
  6126.  
  6127. PVOID               Points to the record in the list being compared 
  6128. PVOID               Points to the application-specified data passed to the 
  6129.                     function 
  6130.  
  6131. Returns 
  6132.  
  6133. -1                  If the first parameter is "less than" the second parameter 
  6134. 0                   If the first parameter is "equal to" the second parameter 
  6135. 1                   If the first parameter is "greater than" the second 
  6136.                     parameter 
  6137.  
  6138.  
  6139. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6140.  
  6141. typedef VOID (* EXPENTRY PFNRECFUNC)(PVOID);
  6142.  
  6143. Input 
  6144.  
  6145. PVOID               Points to a record in the list 
  6146.  
  6147.  
  6148. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6149.  
  6150. typedef BOOL (* EXPENTRY PFNRECMED)(HCLLIST,PVOID);
  6151.  
  6152. Input 
  6153.  
  6154. HCLLIST             Handle to the list to find the median of 
  6155. PVOID               Points to a buffer large enough to hold a single record 
  6156.  
  6157. Output 
  6158.  
  6159. PVOID               Points to a buffer containing the median of the specified 
  6160.                     list 
  6161.  
  6162. Returns 
  6163.  
  6164. TRUE if successful, FALSE otherwise 
  6165.  
  6166.  
  6167. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6168.  
  6169. A 32-bit handle used to specify a memory manager instance.  it is created using 
  6170. the function CmnMemInitialize and is destroyed using the function 
  6171. CmnMemTerminate. 
  6172.  
  6173. Related information 
  6174.  
  6175. o CmnMemInitialize 
  6176. o CmnMemTerminate 
  6177.  
  6178.  
  6179. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6180.  
  6181. typedef struct _CMMEMINFO {
  6182.    USHORT usNumHeaps;
  6183.    ULONG ulSzHeap;
  6184.    ULONG ulMemUsed;
  6185. } CMMEMINFO, FAR *PCMMEMINFO;
  6186.  
  6187. usNumHeaps                    Contains the number of internal heaps to be used 
  6188.                               by the memory management routines.  The default 
  6189.                               is 256. 
  6190. ulSzHeaps                     Contains the size of each heap.  The default is 
  6191.                               61440. 
  6192. ulMemUsed                     Contains the amount of memory currently allocated 
  6193.                               by this memory handle. This field is ignored by 
  6194.                               CmnMemInitialize(). 
  6195.  
  6196.  
  6197. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6198.  
  6199. A 32-bit handle used to specify an object manager instance.  it is created 
  6200. using the function CmnObjInitialize and is destroyed using the function 
  6201. CmnObjTerminate. 
  6202.  
  6203. Related information 
  6204.  
  6205. o CmnObjInitialize 
  6206. o CmnObjTerminate 
  6207.  
  6208.  
  6209. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6210.  
  6211. typedef struct _COOBJECTINFO {
  6212.    HCOOBJECT hcoParent;
  6213.    CHAR achName[MAX_OBJECTNAME+1];
  6214.    ULONG ulSzData;
  6215.    PVOID pvData;
  6216.    USHORT usNumChildren;
  6217.    ULONG ulReserved;
  6218. } COOBJECTINFO, FAR *PCOOBJECTINFO;
  6219.  
  6220. hcoParent                     Specifies the handle of the parent object.  If 
  6221.                               NULL then this is the root object. 
  6222. achName                       Specifies the fully qualified name of the object. 
  6223. ulSzData                      Specifies the size of the object-data. 
  6224. pvData                        Points to the object-data.  Using this field is 
  6225.                               discouraged, since this points to the 
  6226.                               object-manager's copy of the data.  Instead, use 
  6227.                               the CmnObjQueryObjectData function. 
  6228. usNumChildren                 Specifies the number of immediate children. 
  6229. ulReserved                    Reserved, though it might not be zero. 
  6230.  
  6231. Related information 
  6232.  
  6233. o CmnObjQueryObjectData 
  6234.  
  6235.  
  6236. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6237.  
  6238. A 32-bit handle used to specify a set.  It is created using the function 
  6239. CmnSetCreateSet and is destroyed using the function CmnSetDestroySet. 
  6240.  
  6241. Related information 
  6242.  
  6243. o CmnSetCreateSet 
  6244. o CmnSetDestroySet 
  6245.  
  6246.  
  6247. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6248.  
  6249. typedef struct _CSSETINFO {
  6250.    ULONG ulMaxElements;
  6251.    ULONG ulElementsSet;
  6252. } CSSETINFO, FAR *PCSSETINFO;
  6253.  
  6254. ulMaxElements                 specifies the size of the set 
  6255. ulElementsSet                 specifies the number of elements currently set in 
  6256.                               the set 
  6257.  
  6258.  
  6259. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6260.  
  6261. Constant                      Meaning 
  6262. SWS_TIMEOUT_IMMEDIATE         specifies that the function should return 
  6263.                               immediately if the condition fails 
  6264. SWS_TIMEOUT_NEVER             specifies that the function should never return 
  6265.                               until the condition is met 
  6266.  
  6267.  
  6268. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6269.  
  6270. A 32-bit handle used to specify a signal.  It is created using the function 
  6271. CmnSigCreateSignal and is destroyed using the function CmnSigDestroySignal. 
  6272.  
  6273. Related information 
  6274.  
  6275. o CmnSigCreateSignal 
  6276. o CmnSigDestroySignal 
  6277.  
  6278.  
  6279. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6280.  
  6281. A 32-bit handle used to specify a signal list.  It is created using the 
  6282. function CmnSigCreateSignalList and is destroyed using the function 
  6283. CmnSigDestroySignalList. 
  6284.  
  6285. Related information 
  6286.  
  6287. o CmnSigCreateSignalList 
  6288. o CmnSigDestroySignalList 
  6289.  
  6290.  
  6291. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6292.  
  6293. A 32-bit handle used to specify a playground instance.  This is created by the 
  6294. CmnSprCreatePlayground function and is destroyed by the CmnSprDestroyPlayground 
  6295. function.  Sprites must be added to a playground before they can be manipulated 
  6296. in any way. 
  6297.  
  6298. Related information 
  6299.  
  6300. o CmnSprAddSprite 
  6301. o CmnSprCreatePlayground 
  6302. o CmnSprDestroyPlayground 
  6303. o CmnSprRemoveSprite 
  6304.  
  6305.  
  6306. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6307.  
  6308. A 32-bit handle used to specify a sprite instance.  This is created by the 
  6309. CmnSprCreateSprite function and is destroyed by the CmnSprDestroySprite 
  6310. function.  Sprites must be added to a playground before they can be manipulated 
  6311. in any way. 
  6312.  
  6313. Related information 
  6314.  
  6315. o CmnSprAddSprite 
  6316. o CmnSprCreateSprite 
  6317. o CmnSprDestroySprite 
  6318. o CmnSprRemoveSprite 
  6319.  
  6320.  
  6321. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6322.  
  6323. Constant                      Meaning 
  6324. SCTN_TYPE_BYTE                specifies that the ASCII data represents a byte 
  6325.                               of data 
  6326. SCTN_TYPE_SHORT               specifies that the ASCII data represents a short 
  6327.                               integer (2 bytes) 
  6328. SCTN_TYPE_LONG                specifies that the ASCII data represents a long 
  6329.                               integer (4 bytes) 
  6330. SCTN_TYPE_FLOAT               specifies that the ASCII data represents a 
  6331.                               single-precision floating point number 
  6332. SCTN_TYPE_DOUBLE              specifies that the ASCII data represents a 
  6333.                               double-precision floating point number 
  6334.  
  6335. The following are attribute constants which can be or'd with the above type 
  6336. constants. 
  6337.  
  6338. Constant                      Meaning 
  6339. SCTN_ATTR_DECIMAL             specifies that the number represented in ASCII is 
  6340.                               in decimal 
  6341. SCTN_ATTR_HEX                 specifies that the number represented in ASCII is 
  6342.                               in hexadecimal 
  6343.  
  6344.  
  6345. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6346.  
  6347. Constant                      Meaning 
  6348. SPL_TYPE_BYTE                 specifies that the field represents a byte of 
  6349.                               data 
  6350. SPL_TYPE_CHAR                 specifies that the field represents a character 
  6351.                               of data 
  6352. SPL_TYPE_STRING               specifies that the field represents a string of 
  6353.                               characters.  Note that the length of the field 
  6354.                               does not include the terminating `\0'. 
  6355. SPL_TYPE_SHORT                specifies that the field represents a short 
  6356.                               integer (2 bytes) 
  6357. SPL_TYPE_LONG                 specifies that the field represents a long 
  6358.                               integer (4 bytes) 
  6359. SPL_TYPE_FLOAT                specifies that the field represents a 
  6360.                               single-precision floating point number 
  6361. SPL_TYPE_DOUBLE               specifies that the field represents a 
  6362.                               double-precision floating point number 
  6363. SPL_TYPE_RESERVED             specifies that the bytes in the destination 
  6364.                               buffer are to be skipped 
  6365.  
  6366. The following are attribute constants which can be or'd with the numeric type 
  6367. constants listed above. 
  6368.  
  6369. Constant                      Meaning 
  6370. SPL_ATTR_DECIMAL              specifies that the number represented in ASCII is 
  6371.                               in decimal 
  6372. SPL_ATTR_HEX                  specifies that the number represented in ASCII is 
  6373.                               in hexadecimal 
  6374.  
  6375. Return code values are the following: 
  6376.  
  6377. Constant                      Meaning 
  6378. SPL_NOTFOUND                  specifies that the field was empty 
  6379. SPL_FOUND                     specifies that the field was not empty 
  6380.  
  6381.  
  6382. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6383.  
  6384. Constant                      Meaning 
  6385. SPS_LEFT                      Specifies that the string is to be padded on the 
  6386.                               left side. 
  6387. SPS_RIGHT                     Specifies that the string is to be padded on the 
  6388.                               right side. 
  6389.  
  6390.  
  6391. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6392.  
  6393. Command line argument descriptor 
  6394.  
  6395. typedef struct _CSCMDDESC {
  6396.    USHORT usId;
  6397.    CHAR achSwitch[SPCL_MAX_SWITCH+1];
  6398.    USHORT usNumArgs;
  6399.    USHORT usFlags;
  6400.    PFNCMDARG pfnCallback;
  6401. } CSCMDDESC, FAR *PCSCMDDESC;
  6402.  
  6403. usId                          specifies the identifier for the command line 
  6404.                               argument 
  6405. achSwitch                     specifies the string representing the command 
  6406.                               line argument 
  6407. usNumArgs                     specifies the number of arguments the command 
  6408.                               line argument requires 
  6409. usFlags                       specifies a combination of SPCL_FLG_ constants 
  6410. pfnCallback                   points to a callback function (see below) 
  6411.  
  6412. SPCL_FLG_ constants 
  6413.  
  6414. SPCL_FLG_CASESENSITIVE        specifies that achSwitch is case-sensitive 
  6415. SPCL_FLG_SUBSTRING            specifies that achSwitch is a substring of the 
  6416.                               entire command line argument.  If you specify 
  6417.                               this, you must also specify SPCL_FLG_ARGCONCAT. 
  6418. SPCL_FLG_ARGCONCAT            specifies that the first argument is concatenated 
  6419.                               to the command line argument (e.g. "-FPa", where 
  6420.                               "a" is the first argument). 
  6421.  
  6422. PFNCMDARG function 
  6423.  
  6424. typedef BOOL (* EXPENTRY PFNCMDARG)(USHORT,PCHAR *,USHORT);
  6425.  
  6426. Input 
  6427.  
  6428. USHORT              specifies the identifier of the switch 
  6429. PCHAR *             points to an array of arguments to the command line 
  6430.                     argument 
  6431. USHORT              specifies the number of arguments 
  6432.  
  6433. Returns 
  6434.  
  6435. TRUE if the processing was successful, or FALSE otherwise 
  6436.  
  6437.  
  6438. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6439.  
  6440. typedef struct _CSLINEDESC {
  6441.    USHORT usOffset;
  6442.    USHORT usLength;
  6443.    USHORT usType;
  6444. } CSLINEDESC, FAR *PCSLINEDESC;
  6445.  
  6446. usOffset                      specifies the 0-based offset of the field 
  6447. usLength                      specifies the length in bytes of the field 
  6448. usType                        specifies a combination of SPL_ constants 
  6449.  
  6450. Related information 
  6451.  
  6452. o SPL_ constants 
  6453.  
  6454.  
  6455. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6456.  
  6457. typedef VOID (* EXPENTRY PFNCMDERR)(USHORT);
  6458.  
  6459. Input 
  6460.  
  6461. USHORT              Specifies the error code 
  6462.  
  6463.    SPCL_ERR_NOMEMORY   The function could not allocate a required amount of 
  6464.                        memory 
  6465.    SPCL_ERR_NOTENOUGHARGS A command-line switch did not contain enough 
  6466.                        arguments 
  6467.    SPCL_ERR_BADSWITCH  An invalid switch was specified 
  6468.    SPCL_ERR_SWITCHERROR The switch function indicated that an error occurred 
  6469.  
  6470.  
  6471. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6472.  
  6473. Constant                      Meaning 
  6474. VGS_UNREADABLE                specifies that the input should not be readable. 
  6475.                               Each character is displayed as an asterisk ('*'). 
  6476. VGS_REQUIRED                  specifies that an empty string may not be 
  6477.                               returned. 
  6478.  
  6479.  
  6480. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6481.  
  6482. typedef struct _CWPOSITION {
  6483.    ULONG ulSzStruct;
  6484.    SWP swpPosition;
  6485.    USHORT ausExtra[6];
  6486. } CWPOSITION, FAR *PCWPOSITION;
  6487.  
  6488. ulSzStruct                    specifies the size of the structure in bytes 
  6489. swpPosition                   specifies the current size and position 
  6490. ausExtra                      specifies the minimized position and the restored 
  6491.                               size and position 
  6492.